Troubleshooting Start with agent-cli --version, then record the exact operation and error. Inside a session, /session-info helps identify the active model and tools. Do not include credentials or private source code in a public bug report. Collect a baseline before changing settings command -v agent-cli agent-cli --version agent-cli storage status agent-cli storage doctor agent-cli mcp list The first two commands distinguish an old executable earlier on PATH from a failed upgrade. Storage diagnostics separate local startup failures from remote model failures. The MCP list reports saved configuration, not proof that every server is currently connected. In the affected conversation, record /session, /session-info, and /terminal. Reproduce with one small request in a fresh session before clearing or deleting the failing session. Retain the original session for investigation; deletion is not a diagnostic procedure. Recognize local error messages Message or prefix | Meaning and next action | session not found: | The requested session directory is unavailable. Copy an exact identifier from agent-cli sessions list; check that you are using the same user account and storage environment. | invalid transferred session: | Session import could not decode stdin. Supply the harness's transfer format, not Markdown from /export or arbitrary transcript JSON. Preserve the decoder detail after the prefix. | MCP server NAME already exists | Add would duplicate a catalog entry. Inspect agent-cli mcp list; enable the existing entry or deliberately choose another name rather than repeatedly adding it. | TRANSPORT must be stdio or http | The MCP transport option is invalid. Use --transport stdio for a local process or --transport http for a remote endpoint. | --max-turns expects a positive integer | The option is a count, not a duration. Supply a positive whole number such as 6, not 0 or 30s. | limit must be a positive integer | A file-read request supplied an invalid line limit. Ask the agent to retry with a positive limit and a valid offset, not wider filesystem access. | Storage and log locations Location | Purpose | ~/.haskell-agent/config.json | Runtime configuration, including MCP connections; may contain secrets | ~/.haskell-agent/models.json | Custom model and connection catalog | /.haskell-agent/settings.json | Saved project preferences, including auto-approval | ~/.haskell-agent/postgres/postgres.log | Managed PostgreSQL startup and server diagnostics | ~/.haskell-agent/postgres/data | Database files; do not remove to resolve a login or rendering issue | /agent.log | Background-agent output when a background agent was started | Use storage diagnostics to identify the actual state location in the current environment. Do not assume every execution mode writes one universal application log. An interactive /export or agent-cli sessions show SESSION_ID --json provides conversation evidence, but can include private tool output. The installed version did not change nix profile add does not upgrade an existing installation. Use: nix profile list nix profile upgrade --refresh --accept-flake-config haskell-agent Use the actual profile entry name if it differs. Check which executable your shell selects if you have more than one installation. Local storage fails to start Before opening sessions, run: agent-cli storage start agent-cli storage doctor Preserve the diagnostic output. Do not delete storage directories as a first response: they can contain saved conversations and durable state. The managed cluster uses port 55432 by default and a private Unix-socket directory. AGENT_POSTGRES_PORT overrides the port and AGENT_POSTGRES_BIN overrides the directory containing PostgreSQL executables. A custom executable directory must contain a compatible PostgreSQL installation; mixing server versions with an existing data directory is not a repair strategy. - If startup cannot locate PostgreSQL tools, check whether you are running the Nix-packaged executable and whether AGENT_POSTGRES_BIN was overridden. - If connection or socket errors persist, compare storage status with the PostgreSQL log. Check that different shells are using the same storage environment and port. - For schema errors, preserve a backup before running agent-cli storage migrate, then repeat storage doctor. Doctor checks connectivity, not an exhaustive schema comparison. - Before any stop/restart, finish other sessions that depend on this database. Preserve the original error and log excerpt if recovery fails. Interpret storage diagnostics The following are exact success/status messages, not a transcript from your machine: Command/output | Interpretation and action | storage status: managed PostgreSQL is not initialized | No initialized managed cluster. Verify the intended state directory and user before using storage start. | storage status: managed PostgreSQL is stopped | Cluster exists but is not running. Inspect the log, then start it after checking the executable version. | storage status: managed PostgreSQL is running | The managed process is running; use doctor to test a database connection. | storage start: managed PostgreSQL is running and migrations are up to date | Start also initializes storage and applies migrations when needed. It is not a read-only health check. | storage doctor: managed PostgreSQL is healthy; socket: followed by a directory | Status and opening the connection pool succeeded. This does not prove backup integrity, model connectivity or every stored record's correctness. | Doctor reports not initialized/stopped | The error explicitly recommends agent-cli storage start. Follow the backup precaution below for existing data. | Process running but doctor fails | Compare socket directory, port, user permissions and database errors. Do not create a second cluster or delete the original to make the check green. | The managed configuration disables TCP listening. Its port selects a Unix-socket filename, so an unrelated TCP listener on 55432 alone is not a conflict. For socket/lock conflicts inspect the actual server owner and log before stopping anything; never remove a live server's socket or PID file. The packaged PostgreSQL tools, a writable state directory, sufficient disk space and a server version compatible with the data directory are prerequisites. Startup errors identify commands such as initdb or pg_ctl start; preserve their stderr and postgres.log. Back up before schema maintenance - Finish dependent sessions and stop application writers. Record the CLI and PostgreSQL versions, actual state/socket directory and port. Keep the prior executable. - For a running database, create a logical backup using compatible PostgreSQL tools. Store it in a private persistent backup directory, not a conversation attachment. - Verify the dump is readable and rehearse restoration into an isolated cluster before relying on it. If storage cannot start, retain a stopped-cluster snapshot and seek version-specific recovery; do not copy a running data directory as an ordinary backup. - Run agent-cli storage migrate. Success is managed PostgreSQL migrations are up to date. This command also starts storage if necessary; there is no documented downgrade command. - On failure, keep writers stopped, preserve the complete error and log, and correct the diagnosed prerequisite before retrying. Do not alter migration records manually. Restore only into an isolated destination first; verify it with the matching executable before deliberately replacing production state. Example for the default running cluster; replace paths and port with your actual values. Create and secure BACKUP_DIR first. These commands are a procedure, not an executed backup record: pg_dump -h "$HOME/.haskell-agent/postgres/run" -p 55432 -U ha_owner -d haskell_agent -Fc -f "$BACKUP_DIR/haskell-agent.dump" pg_restore --list "$BACKUP_DIR/haskell-agent.dump" agent-cli storage migrate agent-cli storage doctor Listing a dump verifies its catalog can be read, not that a complete restore succeeds. A logical database dump does not include all cluster roles, configuration or non-database session files. Preserve those separately and use the restore checklist. Authentication fails or the wrong account is used - Inspect /session-info and /usage. - Open /login to check the provider connection. - Use /reload-auth after changing credentials outside the agent. - Select the intended model again with /model. For Claude Code, verify claude auth login completed. For a custom endpoint, check the named environment variable and the configured base URL. Never paste an API key into the conversation to diagnose it. Distinguish provider error categories Symptom | Check | Recovery | HTTP 401 or expired credentials | Selected connection and credential source | Re-authenticate that provider; reload supported credentials and retry one small request | HTTP 403 or access denied | Account entitlement and organization policy | Use an authorized model/account; extra shell permissions do not grant provider access | HTTP 404 or model not found | Exact model identifier, connection base URL, and API protocol | Correct the catalog or endpoint; verify with the provider's model listing | HTTP 429 | Usage limits, reset time, and API credit | Wait for reset or deliberately change accounts/models; do not repeatedly submit the same request | Connection refused, DNS, or TLS failure | Server process, host/port, VPN/proxy, and certificate trust | Restore endpoint connectivity; do not disable certificate verification as a default fix | Context capacity or compaction error | Model's configured context window and conversation size | Correct the catalog limit, compact where supported, or begin a smaller fresh task | The exact message is provider-dependent. For custom models, a reachable HTTP endpoint can still implement the wrong protocol. A chat-only endpoint is not automatically a Responses API endpoint. Check custom model configuration before changing authentication. The agent is waiting after a usage limit Interactive sessions can wait for an account's reset time when another configured account cannot take over. /usage displays available usage information. Press Esc to cancel the wait, or deliberately select another available model. Subscription and API-credit billing are different. A tool is missing or denied Check whether the active model supports the tool and whether it is enabled. /shell reports shell selection, /computer-use controls desktop capability, and /mcp displays external server status. A denial can be an approval-policy decision, a plan-mode restriction, an operating-system permission, or a sandbox restriction. Read the error rather than enabling unrestricted execution indiscriminately. If the optional GHCi tool cannot find ghci, start with a Nix-provided GHC: nix shell nixpkgs#ghc -c agent-cli --ghci An MCP server is unavailable Use /mcp to inspect the server. Verify the command exists or the HTTP endpoint is reachable. Use i to re-authorize HTTP and r to restart connections. Interactive startup is progressive, so a server may still be connecting when the prompt first appears. If a mutation might already have succeeded remotely, inspect its outcome before retrying it. - Local command not found: run the configured executable's version or help command in the same environment. Prefer a Nix-provided command rather than relying on a GUI application's different PATH. - Local process starts but initialization fails: confirm it speaks MCP over stdio, not an HTTP service; stdout must be reserved for protocol messages. Put diagnostic logging on stderr. - Remote authorization repeats: verify the exact endpoint URL and requested OAuth scopes. Re-authorize with agent-cli mcp login URL or the manager's i action. - Connected but tool absent: inspect that server's tool list and enabled state. Some models discover tools on demand; ask for the specific operation. - Configuration changed but old behavior remains: restart the MCP runtime with /mcp, then r, and inspect its new status. Worktree creation fails Managed worktrees fetch the selected remote by default. Confirm Git access, remote configuration, and network connectivity. A fetch failure intentionally stops creation rather than using stale state. If you intend to work without fetching, configure worktree.fetchLatestUpstream as described in worktrees. Do not assume a new worktree includes uncommitted files from your current checkout. git status --short git remote -v git branch --show-current git worktree list These commands show local changes, configured remotes, the current branch, and registered worktrees without deleting anything. Redact embedded credentials from remote URLs before sharing output. A clean original checkout and a managed worktree are different directories; use /copy-path to verify which one the agent is editing. Text selection or terminal rendering is unexpected Use /mouse off for native text selection. Run /terminal to inspect terminal capabilities. If fullscreen rendering is unsuitable, try: agent-cli --minimal When reporting a terminal issue, include the terminal application, operating system, selected rendering mode, and a redacted screenshot. If paste produces an image attachment rather than text, inspect /attachments and clear unwanted images with /clear-attachments before submitting. If a shortcut is intercepted by the terminal, use the equivalent slash command and consult keybindings. Clipboard image support on Linux depends on the relevant Wayland/X11 clipboard utilities. A skill is not discovered - Confirm the filename is SKILL.md inside the skill's directory, not a loose Markdown file elsewhere. - Check the name and description front matter against the skill reference, including directory/name agreement. - Run /skills reload, then /skills, from the intended project. - Check that the session was not started with --no-skills. For duplicate names, inspect discovery precedence rather than assuming the last edited file wins. Compaction refuses a custom model Set context_window in the model catalog to the server's documented limit. The harness refuses to guess a portable model's context capacity. Prepare a useful report Reduce the issue to one reproducible operation and include: - The CLI version, operating system, and terminal application. - The exact command or sequence of actions, with secrets removed. - What you expected, what happened, and the complete relevant error. - The selected provider and rendering mode, and whether the issue occurs in a fresh session. For example: “In fullscreen mode, after /mouse off, native selection still does not work in this terminal; minimal mode works.” This is more actionable than “the terminal is broken.” Review screenshots and transcripts for credentials, personal data, and private code before sharing them.