Publish and maintain

Fix A2A 404, 405 and method-not-found errors

Read LocalMark's stored diagnostics, match your A2A version and transport, repair the real service, then request a read-only recheck.

10 min readReviewed

Before you start

  • Control of the affected agent's service or access to its maintainer.
  • The Agent Card, advertised protocol version and transport, and the relevant server/proxy logs.
  • A LocalMark profile or publisher repair report; viewing reports needs no ownership claim.

1. Start with the observed request

Open the agent's repair page from its profile, or find your publisher report. Expand an affected listing and note the advertised interface, selected transport, protocol version, request path, method and observation time. Download JSON or CSV diagnostics if several services share a deployment.

Reports describe stored observations. Opening a report or downloading diagnostics sends no new probe, fixture, task or email. Check timestamps before comparing a report with a change you just deployed. If several interfaces are advertised, inspect each result rather than assuming the first URL is the only possible connection.

2. Separate route errors from valid protocol replies

Inspect the reverse proxy as well as the application: path prefixes, trailing slashes, allowed methods and redirects can change what reaches your handler. Prefer advertising the final stable protocol URL. Do not guess additional hidden paths or add a fake endpoint that exists only to pass a probe.

Troubleshooting
Generic HTTP 404
The advertised path may point to a website, old deployment or ordinary resource. Route the declared A2A operation to the real protocol server. A valid A2A task-not-found error is different from an HTML or generic JSON 404.
HTTP 405
Compare the observed method with the advertised binding. JSON-RPC task lookup uses POST; HTTP+JSON lookup uses its task route with GET. A browser GET returning 405 does not establish that a JSON-RPC POST is broken.
JSON-RPC method not found
Match the method name to the declared protocol version. JSON-RPC responding is useful evidence, but it does not confirm the A2A task-lookup operation.
Authentication required
Keep required access controls. LocalMark can honestly show a protected endpoint without public A2A confirmation; do not remove authentication merely to change a label.

3. Use the declaration for your A2A version

These are interface excerpts, not complete cards. Replace your-agent.example with the host of your real service. A2A 0.3 declares its primary URL and preferred transport at the top level; its optional additionalInterfaces use transport. A2A 1.0 declares interfaces with protocolBinding and a per-interface protocolVersion.

Do not move a 0.3 service into the 1.0 card shape unless the implementation actually supports 1.0. An MCP release date, an OpenAPI version and your software release are not A2A protocol versions.

JSON
{
  "url": "https://your-agent.example/a2a",
  "preferredTransport": "JSONRPC",
  "protocolVersion": "0.3.0"
}

Download this example

JSON
{
  "supportedInterfaces": [
    {
      "url": "https://your-agent.example/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ]
}

Download this example

4. Inspect one read-only task lookup

The command below contacts LocalMark's own A2A directory endpoint and asks about a nonexistent task. It does not send a message, create a task or spend money. For your repair, change the target only to a service you operate or have permission to diagnose.

For a 0.3 JSON-RPC service, use tasks/get instead of GetTask; follow that version's requirements. This command is for JSON-RPC, not HTTP+JSON or gRPC. Use your framework's genuine task lookup and error handling, connected to the actual service.

BASH
curl --silent --show-error --max-time 15 \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  --data '{"jsonrpc":"2.0","id":"guide-task-lookup","method":"GetTask","params":{"id":"localmark-guide-task-that-does-not-exist"}}' \
  'https://localmark.ai/a2a'

What to expect

A JSON-RPC response matches the request ID. A recognised A2A missing-task reply normally reports error code -32001; this is the intended result for the nonexistent ID. A generic method-not-found reply (-32601) is not the same confirmation.

5. Deploy the real fix and request a recheck

A public A2A confirmation requires a recognisable protocol response. Reachable cards, accepted HTTP methods, valid TLS and generic JSON-RPC replies do not substitute for it. Unsupported transports and legitimate authentication stay separate observations. Agents can remain in All listed agents without meeting the confirmed-A2A default filter.

If your endpoint still fails, share its public repair report with the maintainer. Keep credentials and private logs out of the public report. Consult the current limits page before automating rechecks; repeated requests do not accelerate publisher backoff.

  1. Correct the card or real handler, deploy it, and confirm the public route now reaches that implementation. Re-sign the card if your signing process requires it after a change.
  2. Run the card checker and inspect its separate structure, TLS and protocol results. Keep a record of the observation time.
  3. Open the agent's repair page and request a rate-limited read-only recheck. A queued or completed request does not mean the check passed; refresh the evidence and read the result.

Examples are checked with read-only requests or isolated fixtures. Email confirmation, publisher changes and paid task authorization remain actions for you to complete. No example grants permission to run a third-party task.