Troubleshooting
Fix common a2a-wrapper problems. Model not available, authentication errors, a missing core build or stale dependencies, unreachable agents, Codex sandbox failures in Docker, and expired sessions.
Model "..." is not available
The model you configured is not enabled for your account. This happens with a2a-copilot when a pinned model is outside your plan.
- Set
"model": "auto"(or--model auto) to let Copilot choose. - Or pick a model your plan includes.
Authentication errors on startup
| Wrapper | Check |
|---|---|
a2a-copilot | Run gh auth login or set GITHUB_TOKEN, and confirm your account has Copilot access |
a2a-claude | ANTHROPIC_API_KEY is exported in the same shell that starts the agent |
a2a-codex | OPENAI_API_KEY is set, or codex login was run. With subscription auth set CODEX_MODEL; tokens from codex login expire, so re-run it or use an API key for unattended use |
a2a-antigravity | Run a2a-antigravity setup once, and set a Gemini key or Vertex/ADC credentials |
"does not provide an export named …" or build errors after pulling
Wrappers import @a2a-wrapper/core from its compiled output, which is git-ignored. After pulling new commits:
npm install
npx turbo run build"Cannot reach an agent" or connection refused
- Confirm the agent is running and on the port you expect.
- If it binds to
127.0.0.1, it is reachable only from the same machine. Inside Docker, publish the port with-p. - Fetch
http://HOST:PORT/healthand the agent card to check.
The task never finishes, or returns an error artifact
- Increase
timeouts.prompt(milliseconds) for long tasks. - Switch to
message/streamfor long-running work. - For
a2a-claude, check for arate_limitevent; rate limits fail the task.
The agent forgot the conversation
The next turn started a fresh session. Either the contextId changed between messages, or the session expired because session.ttl is set. Reuse the same contextId and check ttl. See sessions.
Shell commands fail in Docker (a2a-codex)
Codex wraps commands in Bubblewrap, which needs Linux user namespaces that standard containers block. Run with --privileged or --security-opt=seccomp:unconfined, or run without Docker for local development. See Docker.
A client receives odd or duplicated artifact chunks
Streamed artifact chunks use append: true. If your client does not handle appends, turn streaming off with features.streamArtifactChunks: false (the default), which publishes one complete artifact.
Local models do not call tools (a2a-copilot BYOK)
The model must support native tool calling. Some small or older local models print tool calls as plain text and will not work. Use a tool-capable model.
Still stuck?
Search the GitHub issues or open a new one with the package, its version, your Node version, a redacted config and the logs.
Build your own wrapper
Add a new backend to a2a-wrapper by implementing the A2AExecutor interface and wiring it with createCli from @a2a-wrapper/core. A minimal TypeScript example and the steps to add it to the monorepo.
HTTP API
The HTTP surface every a2a-wrapper agent exposes. The agent card endpoint, A2A JSON-RPC and REST routes, health check, and example requests for message/send, message/stream, tasks/get and tasks/cancel.