Troubleshooting

Fix common problems

Find the symptom, run the commands, and read the reason before widening any access.

Device is offline

Check that the service is running and can reach the ADC address. A sleeping laptop is offline by design and reconnects on wake.

adc-node status
adc-node logs
adc-node restart

The agent sees no folders

Check the local access mode first, then the device policy in the console, then the Agent access. Each layer can only narrow the one before it.

adc-node status
adc-node roots list
adc-node roots add ~/work --label Work

A call is denied

Read the returned reason before widening access. Check the tool list in Agent access, the device's execution switch and read-only folders.

adc access show my-agent --json
adc device show DEVICE --json

A call is waiting for approval

Open Approvals before it expires and check the agent, device, tool and path.

adc approval list --json
adc approval approve APPROVAL_ID --json

unknown_outcome

The change may have happened, but no receipt can be proven. Check the target and Activity first; retry only with the original idempotency key.

adc audit show INVOCATION_ID --json
adc task result JOB_ID --json

Self-hosted: /health returns 503

Check PostgreSQL availability and disk space, restore the database connection, then restart the app.

docker compose --env-file .env -f deploy/compose.yaml ps

When asking for help, include the error code, invocation ID and connector logs. Never paste access keys, cookies, device keys or file contents into a public issue.