# Troubleshooting (/docs/guides/troubleshooting)



## `Model "..." is not available` [#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 [#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 [#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:

```bash
npm install
npx turbo run build
```

## "Cannot reach an agent" or connection refused [#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/health` and the agent card to check.

## The task never finishes, or returns an error artifact [#the-task-never-finishes-or-returns-an-error-artifact]

* Increase `timeouts.prompt` (milliseconds) for long tasks.
* Switch to `message/stream` for long-running work.
* For `a2a-claude`, check for a `rate_limit` event; rate limits fail the task.

## The agent forgot the conversation [#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](/docs/concepts/sessions).

## Shell commands fail in Docker (a2a-codex) [#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](/docs/guides/docker).

## A client receives odd or duplicated artifact chunks [#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) [#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? [#still-stuck]

Search the [GitHub issues](https://github.com/shashikanth-gs/a2a-wrapper/issues) or open a new one with the package, its version, your Node version, a redacted config and the logs.