IAS — Troubleshooting

Solutions for common IAS issues including agent connectivity, job execution, authentication, bootstrap failures, and worker problems.

This guide covers the most common issues you may encounter when working with IAS and how to resolve them. Start with the diagnostic tool, then find your specific issue below.

Diagnostics

Before diving into specific issues, run the built-in diagnostic tool:

ias doctor

This checks your Node.js version, Git installation, GitHub CLI authentication, worker configuration, control plane connectivity, and repository mappings. Follow the suggestions it provides. For machine-readable output:

ias doctor --json

You can also inspect your full configuration:

ias print-config

Common Issues

Agent Not Showing Online

Symptoms: The Console shows no active agents, or the agent appears offline even though you started it.

Step 1 -- Verify worker configuration:

ias doctor

Confirm these values are correct in ~/.ias/worker.json:

controlPlane.convexDeploymentUrl must be https://<deployment>.convex.cloud (the Convex deployment URL, not the site URL)
controlPlane.workspaceSlug must match your workspace slug in the Console

Step 2 -- Check authentication:

ias auth status

If the token is expired or missing, re-authenticate:

ias auth login

Step 3 -- Verify the worker process is running:

ias worker status

If the worker is not running, start it:

ias worker start

Step 4 -- Check network connectivity:

The worker needs to reach https://<deployment>.convex.site. Verify that firewalls, proxies, or VPNs are not blocking the connection. Corporate networks sometimes block WebSocket connections that Convex relies on.

Jobs Stuck in Pending

Symptoms: Jobs appear in the Console with a "pending" status but are never claimed.

Check	Command	Fix
Is a worker running?	`ias worker status`	Start with `ias worker start`
Is the repo mapped?	`ias doctor` (look at `repos.mappings`)	`ias repo link /path/to/repo`
Is the local path valid?	Inspect `~/.ias/worker.json`	Update `localPath` to point to an existing Git checkout
Is the right executor running?	Check which worker types are active	Start both with `ias agent start`

Execution mode compatibility:

Workers and runners handle different job types. If only one is running, certain jobs will not be claimed:

Job Types	Required Executor
`install_ias`, `create_run`, `context_architect`, `apply_decision`, `update_git_policy`, `git_repair`	CLI worker (`ias worker start`)
`work`, `pr_review`	Hybrid runner (`ias runner start`)

Use ias agent start to start both the worker and runner together, or start them independently.

Authentication Issues

Device login fails:

Check that the Console app URL is correct and reachable:

ias print-config

The consoleAppUrl must point to a running Console instance. For local development, this is typically http://localhost:3000. If the CLI cannot open your browser automatically, copy the URL from the terminal output and open it manually:

ias auth login --open false

Token expired:

Re-authenticate:

ias auth login

Run ias auth status to verify the new token is active.

Console UI shows "UNAUTHENTICATED" errors:

This typically means the Clerk-to-Convex auth integration is misconfigured:

In the Clerk Dashboard, verify a JWT template named exactly convex exists
Confirm the Issuer URL is set as CLERK_JWT_ISSUER_DOMAIN in Convex environment variables
Redeploy Convex if you changed environment variables

Bootstrap Failures

"Not a git repo":

The target directory must be an initialized Git repository. Either initialize Git first:

git init /path/to/repo

Or use the guided installer, which offers to initialize Git for you:

ias install /path/to/repo --guided

"Tracked/staged changes":

IAS requires a clean working tree when committing the bootstrap. Commit or stash your changes first:

cd /path/to/repo
git stash
ias install .
git stash pop

Or bootstrap without committing (you can commit manually later):

ias bootstrap /path/to/repo --commit false

Bootstrap succeeded but files are not visible:

The bootstrap creates files on a branch (default: ias/bootstrap). Check which branch you are on:

git branch

Switch to the bootstrap branch to see the files, or merge them into your default branch. See Install & Bootstrap for the full workflow.

Build Context Failures

Symptom: The "Build Context" job fails or produces no output.

Ensure bootstrap completed first:

Build Context reads from docs/ias/project-context.md and other scaffold files. If these do not exist, the job will fail. Verify that IAS is installed:

ls docs/ias/project-context.md

If the file is missing, re-run the bootstrap:

ias install /path/to/repo --force

Check that the repo is linked:

ias doctor

The repo must be mapped in ~/.ias/worker.json for the worker to claim build context jobs. If not mapped:

ias repo link /path/to/repo

Decision Requests Not Appearing

Symptoms: An agent reports creating a decision request, but it does not appear in the Console Inbox.

Check workspace scope:

Decision requests are scoped to a workspace. Verify you are viewing the correct workspace in the Console. Check that the agent creating the request is authenticated to the same workspace:

ias auth status

Check workstream filters:

The Console Inbox can be filtered by workstream. If you have a workstream filter active, the decision request may be in a different workstream or unscoped. Clear the filter to see all requests.

Check auto-promotion:

Decision requests go through an auto-promotion step. If the request was created with confidence above the auto-promote threshold, it may have been auto-resolved without appearing in the Inbox. Check the run's decision log in the repository.

Worker Disconnects

Symptoms: The worker goes offline periodically or loses connection.

Check network stability:

The worker maintains a connection to the Convex backend. Unstable networks -- especially VPNs, corporate proxies, or intermittent Wi-Fi -- can cause disconnections.

Restart the worker:

ias worker stop
ias worker start

Or run in daemon mode for automatic restarts:

ias worker start --daemon

Check worker logs:

ias worker logs
ias worker logs --which err

Look for connection errors, authentication failures, or unexpected exits. For more detailed output:

ias worker start --verbose

Runner-Specific Issues

Runner Not Found

If ias agent start reports that the hybrid runner is not found:

Verify IAS was bootstrapped with the hybrid or full profile
Check that scripts/ias-runner/run.mjs exists in your repository
Install runner dependencies: cd scripts/ias-runner && npm ci

Jobs Timing Out

The runner enforces a per-job timeout (default: 30 minutes). If jobs consistently time out:

Break large tasks into smaller, more focused jobs
Increase the timeout via maxTurnMs in docs/ias/runs/<run>/runner/config.json
Check whether the agent is stuck in a loop (review runner logs)

Stuck Lock File

If the runner reports a lock conflict after a crash:

ias runner recover

Or for a specific run:

node scripts/ias-runner/run.mjs recover --latest

This clears stuck locks and moves any interrupted jobs back to the pending state.

Quick Reference

Problem	First Command to Run
Agent not connecting	`ias doctor`
Jobs not being claimed	`ias worker status` then `ias doctor`
Auth failures	`ias auth status` then `ias auth login`
Bootstrap failed	Check `git status` and re-run `ias install`
Build context failed	`ls docs/ias/project-context.md`
Decision requests missing	Check workspace and workstream filters
Worker disconnects	`ias worker logs --which err`
Runner lock stuck	`ias runner recover`
Config issues	`ias print-config`

Getting Help

If these solutions do not resolve your issue:

Run ias doctor --json and review the full diagnostic output
Check worker logs: ias worker logs and ias worker logs --which err
Verify your configuration: ias print-config
Review the Architecture page to understand the system components and data flow

Troubleshooting

On this page