| Symptom | Meaning | Do |
|---|---|---|
You are not signed in., exit 4 | No session for the platform calls. | telnyx-acp login, or TELNYX_API_KEY in the environment for scripts. |
Your session has expired., exit 4, or a dev turn that fails with Your session has expired; dev needs a key to reach the model | The session renews itself from the refresh token under an hour; this is a renewal the platform refused, a revoked refresh token for example, or a session with no refresh token to renew from. The hint carries the refusal. | telnyx-acp login (in another terminal under dev; the next turn picks it up). Or TELNYX_API_KEY in the environment, in .env for dev. |
agent.json has N problems, with a field and a fix per line | validate found the problem before anything shipped or started. | Fix the named field; validate again. |
A turn fails with OpenAI API key required for OpenAI models (code 10015), or the Anthropic, Google or Groq variant | The model is a third-party one and the key is not stored. | telnyx-acp add secret OPENAI_API_KEY; OPENAI_API_KEY=… in .env for dev. |
telnyx-acp 0.1.0-beta.7 is available (you have 0.1.0-beta.6): telnyx-acp update on stderr | A newer release exists; the CLI checks once a day on a terminal. | telnyx-acp update. TELNYX_ACP_NO_UPDATE_CHECK=1 silences the notice. |
cannot find a release of telnyx-acp: not on npm, and gh is not signed in …, exit 1 | update asks npm first, then GitHub Releases through the GitHub CLI (Telnyx testers on a pre-release build). | gh auth login, then telnyx-acp update again; or run the installer one-liner from Utilities. |
required option '--conversation <id>' not specified | invoke and rpc need the conversation’s name. | Add --conversation <id>. |
no `telnyx-acp dev` session in this project (.telnyx/dev.json is missing) | --local found no running dev for this project. | Start telnyx-acp dev in the project directory. |
cannot reach http://127.0.0.1:8787: fetch failed | dev stopped, or is not listening on that port. | Restart dev; --port if something else holds 8787. |
A second dev for the same project is refused | One listener per project. | Stop the other one. |
| Webhooks answer 401 | The signature could not be verified: TELNYX_PUBLIC_KEY is missing or wrong. | telnyx-acp add secret TELNYX_PUBLIC_KEY with the account’s public key, then deploy. |
A webhook answers 501 channel handler not implemented | A texml_application channel. | Not available in the beta phase; use a messaging profile, a Call Control application, an email inbox or the browser page. |
<field> is not set this way, exit 2 | set was given a field another verb owns. | Use the verb the message names: add phone, add channel, add tool or add secret; instructions.md is edited directly; name is the directory’s, kind and entry change through export, and deployed is deploy’s record. |
… would leave agent.json with N problems; nothing written | The set or unset would break validation. | Fix the value; each line names the field and the fix. |
the platform does not roll back <name>: it owns the actor type … | Rollback is refused for a function that owns its actor type. | telnyx-acp versions <name> shows each revision’s git short SHA; check it out and deploy. |
this directory is already an agent project (<name>); create makes a new one, exit 2 | create ran inside a project. | Run it from the directory above, or change this project with add and set; --force nests one anyway. |
| A phone abroad texts the number and nothing happens | The number’s texting is domestic; deploy and status say domestic texts only or cannot receive international SMS on its line. | Use a number whose features include international SMS, or test with telnyx-acp text. |
A text or an email got no reply, and logs has {"delivery":"failed"…} | The channel’s API refused the reply with a 5xx or a 429, or did not answer; the reply is retried for about an hour. "gave up" is a 4xx the API would keep refusing, or the hour spent. | Read the line’s status and error; a 4xx names what to fix on the number or the inbox. |
| A call connects but stays silent | The media never reached the agent, or a turn failed after it did: recognition, the model or synthesis. | telnyx-acp logs --since 5m: a voiceCall line with streaming.failed carries the platform’s reason; a voiceTurn line whose outcome is not completed, or a modelStream error, names the stage. |
telnyx-edge is not installed or not on PATH., or telnyx-edge <version> is older than the 0.5.7 this CLI needs., exit 3 | The verb shells out to telnyx-edge. | Install or update it from its releases; TELNYX_EDGE_BIN points the CLI at a copy elsewhere. |
A deployed invoke says is waiting for approval and names no approval id | agent.json has an ask approval; the platform does not keep the approval to decide yet. | telnyx-acp unset approvals.<tool> and deploy; use ask under dev for now. |
invoke ends with a line instead of a reply | The run paused for an approval, was canceled, or produced no reply. | The line says which; for an approval, rpc … approve <id> or deny <id>. |
telnyx-acp status shows what is deployed and whether each webhook still points at the agent; logs reads the log lines.