Troubleshooting

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, local agent 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 local agent configuration:

ias doctor

Confirm these values are correct in ~/.ias/agent.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 local runtime is running:

ias status

If the runtime is not running, start it:

ias start

Step 4 -- Check network connectivity:

The local runtime 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.

Execution mode compatibility:

The unified local runtime handles operational and managed work job types through one operator-facing command:

Use ias start for foreground mode or ias start --daemon for background mode.

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:

1. In the Clerk Dashboard, verify a JWT template named exactly convex exists
2. Confirm the Issuer URL is set as CLERK_JWT_ISSUER_DOMAIN in Convex environment variables
3. 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/agent.json for the local runtime 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.

Runtime Disconnects

Symptoms: The local runtime goes offline periodically or loses connection.

Check network stability:

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

Restart the runtime:

ias stop
ias start

Or run in daemon mode for automatic restarts:

ias start --daemon

Check runtime logs:

ias logs
ias logs --which err

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

ias start

Managed Work-Specific Issues

Managed Work Not Available

If managed work jobs are not being claimed:

• Verify IAS was bootstrapped with the runtime or full profile
• Run ias doctor and follow any local runtime or repo-mapping guidance
• Restart the local runtime with ias start

Jobs Timing Out

The managed runtime 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>/runtime/config.json
• Check whether the agent is stuck in a loop (review runtime logs)

Stuck Lock File

If an automated-mode internal lock conflict appears after a crash:

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

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

Quick Reference

Getting Help

If these solutions do not resolve your issue:

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