Troubleshooting

Conductor issues

Conductor: not running when I run any command

The Conductor process stopped or was never started.

# Start it
defiant watch start

# Check if it starts successfully
defiant watch status

# If it fails to start, check the log
defiant watch logs --lines 50

Common causes:

• Port conflict: another process is using the IPC socket path. rm ~/.defiant/ipc/conductor.sock and retry.
• Bad credentials: defiant config check to validate your API keys.
• Node.js version: Defiant requires Node.js 20+. node --version.

Conductor starts but immediately exits

Check the log:

defiant watch logs --lines 100

Common causes:

• Invalid ANTHROPIC_API_KEY: the Conductor validates the key on startup. Run defiant config check.
• Supabase unreachable: the Conductor connects to Supabase on startup. Check your SUPABASE_URL.
• Corrupted event log: ~/.defiant/events.db may be corrupt. Back it up and remove it to reset: mv ~/.defiant/events.db ~/.defiant/events.db.bak.

IPC socket permission error

Error: EACCES: permission denied, connect '~/.defiant/ipc/conductor.sock'

The socket has wrong permissions or was created by a different user:

ls -la ~/.defiant/ipc/
rm ~/.defiant/ipc/conductor.sock
defiant watch start

---

Sprint issues

Sprint is stuck in INTAKE

The Captain agent is taking longer than expected. Check the agent log:

defiant sprint events spr_01hw... --agent captain
defiant watch logs --follow

Common causes:

• Token budget exhausted: defiant watch status shows red throttle state. Wait for the budget to reset (midnight UTC) or increase the daily budget.
• Anthropic API rate limit: the Conductor retries automatically with exponential backoff, but a 429 can cause a long delay.
• Ambiguous goal: the Captain may be waiting for an inbox resolution. Check defiant inbox list.

Sprint moved to BLOCKED

An automated gate failed. Check the inbox:

defiant inbox list
defiant inbox show <inbox-id>

Resolve with:

defiant inbox resolve <inbox-id> --response "Your decision here"

The sprint will retry from the last checkpoint.

Sprint FAILED

defiant medic diagnose --sprint spr_01hw...

The Medic produces a structured diagnosis. Common failure patterns:

Pattern	Cause	Resolution
typecheck_failure	Builder produced TypeScript errors it couldn’t fix	Lower complexity; split the sprint
test_failure_persistent	Tests fail and Builder cannot fix within budget	Inspect the PR; fix manually or retry
mandate_violation_unresolvable	A blocking mandate cannot be satisfied	Review the mandate; override or fix the architecture
budget_exhaustion	Task exceeded 200k token budget	Split the task into smaller pieces
github_api_error	GitHub API returned an error	Check your GITHUB_TOKEN scopes
infrastructure_missing	Sprint required infrastructure that doesn’t exist	Create the infrastructure manually first

Sprint produces code that doesn’t match my intent

The Captain may have parsed the goal differently than you intended. Review the sprint brief:

defiant sprint events spr_01hw... --type agent.completed --agent captain

For the next sprint, be more specific in the goal. See Quickstart: Tips for writing good sprint goals.

PR created by Builder is failing CI

The Builder runs typecheck and lint before opening the PR, but your CI may run additional checks. Common issues:

• Test coverage below threshold: If your CI enforces coverage, the Builder may have written tests that don’t cover enough paths. Review the PR and add tests, or lower the threshold for this sprint via inbox.
• Linting rules not in the Builder’s context: The Builder reads your .eslintrc but may miss project-specific rules. Add a note to the sprint goal: “Follow the ESLint rules in .eslintrc exactly.”
• Environment variables missing in CI: The new code may reference env vars that aren’t set in CI. Add them to your CI secrets.

---

Mandate violations

Mandate check failing locally

defiant mandates check --mandate mandate_7

Read the violation message carefully — it includes the file and line number. Fix the issue and re-run.

Common mandate violations:

mandate_15 (no console.log):

# Find all console.log in source
grep -r "console\.log" src/
# Remove them; use structured logging instead

mandate_25 (no hardcoded secrets):

# False positive — pattern matched a test or example
# Add to .defiantignore:
tests/fixtures/example-response.json

mandate_8 (dependency hygiene — GPL license):

# Find which dependency is GPL
defiant mandates check --mandate mandate_8 --verbose
# Replace with a MIT/Apache alternative

mandate_44 (RLS on user data tables):

# The migration is missing RLS policies
# Add to the migration file:
ALTER TABLE user_profiles ENABLE ROW LEVEL SECURITY;
CREATE POLICY "users_own_profile" ON user_profiles
  FOR ALL USING (auth.uid() = user_id);

False positive in mandate check

If a mandate check is flagging code that is actually compliant, create a .defiantignore file:

.defiantignore

# Exclude generated files from mandate checks
src/generated/**
# Exclude test fixtures
tests/fixtures/**

Or add an inline suppression comment:

const result = db.query(`SELECT * FROM logs`); // defiant-ignore: mandate_27 (read-only log query, no user input)

Suppressions are logged and surfaced in compliance exports.

---

Token budget issues

Daily budget exhausted

defiant watch status
# Token usage today: 2,000,000 / 2,000,000 (red)

Options:

1. Wait — budget resets at midnight UTC.
2. Increase the budget — defiant config set token_budget_daily 4000000.
3. Reduce sprint size — split large goals into smaller sprints.

Per-task budget exhausted mid-sprint

The Builder checkpoints its work and creates an inbox item. The partial implementation is in a WIP commit on the sprint branch. Options:

• Resolve the inbox item to retry with a higher per-task budget.
• Split the task in a new sprint with a narrower goal.

---

GitHub integration issues

Builder can’t push to the repository

Error: remote: Permission to yourorg/my-app.git denied to github-actions[bot].

Check the GitHub token scopes:

defiant config check
# [FAIL] GITHUB_TOKEN — missing scope: repo

The token needs the repo scope (not just public_repo).

PR auto-merge not working

Ensure:

1. “Allow auto-merge” is enabled in repository settings.
2. Branch protection is configured with the defiant/mandate-check status as a required check.
3. The GitHub token has permission to merge PRs (needs repo scope).

---

Supabase issues

CONDUCTOR_OFFLINE error from REST API

The REST API calls the Conductor via the Supabase Edge Function, which calls your local machine. This requires:

• The Conductor to be running (defiant watch status)
• The Edge Function to have network access to your machine (not possible from Supabase cloud to your localhost)

For cloud deployment, the Conductor must run on a server, not your local machine. See the deployment guide (coming soon).

Event log not syncing to Supabase

The local SQLite event log and the Supabase event log sync automatically. If they diverge:

defiant events sync --force

---

Getting help

If you can’t resolve an issue:

1. Run defiant diagnostic — collects logs, config (credentials redacted), and system info.
2. Open an issue on GitHub with the diagnostic output.
3. Check the Glossary for term definitions.

defiant diagnostic --output defiant-diagnostic.zip
# Attach defiant-diagnostic.zip to your GitHub issue