Troubleshooting

Common failure modes and how to diagnose them. If something's not here, check the FAQ or open an issue.

MCP server isn't being picked up by the agent

Symptoms. You ask the agent "list my cards" and it doesn't call any Ideafy tool. claude mcp list (or platform equivalent) doesn't show ideafy.

Check.

Config file. Open .claude/settings.json (or the platform's config file) in the project root. Is there an mcpServers.ideafy entry? If not, run Install Ideafy MCP from project settings
Agent restart. Most agent CLIs read MCP config on startup. Restart the agent after a config change
Path is correct. The args array should point at an index.ts that actually exists. If Ideafy was reinstalled or moved, the path may be stale — reinstall from project settings
npx tsx can find the file. Run npx tsx <path-to-index.ts> --help from a terminal. If it errors, the node environment is wrong

Pool tools aren't available

Symptoms. Agent tries to call pool_push and says "tool not found" or "project not linked to a team."

Check.

Edition. Are you on the Team edition? Pool tools ship only there
Signed in. Settings → Account — are you authenticated? Solo-mode editions don't have pool tools
Team link. Open the project settings modal. Is the Team dropdown set to a team you're a member of? Pool sync requires the link
Subscription status. If your team's subscription is expired, past_due, canceled, or grace, pool writes are blocked. Pool reads still work. See Subscription states

"Project not found" from MCP tools

Symptoms. The agent calls get_project_by_folder or list_cards and gets "project not found."

Check.

Working directory. The MCP server resolves projects by their folderPath. The agent has to be running from inside the project directory (or pass the absolute path explicitly). Check the agent's CWD
Project registered in Ideafy. Open Ideafy — is the project in the sidebar? If not, create it first via + Add Project
Path typo or symlink. If the project was registered with a symlinked path and the agent is running from the canonical path (or vice versa), the paths don't match. Use the canonical path consistently

Dev server port collision

Symptoms. The card modal shows "Dev server failed to start — port 3031 already in use."

Check.

Another Ideafy card already on that port. Open the board, find the card using port 3031, stop its dev server from the card modal header
Non-Ideafy process on that port. Run lsof -i :3031 in a terminal. Kill the process or configure Ideafy to start at a higher port
Stale PID from a crashed card. If an earlier card crashed, its PID may be in the database but the process is dead. Reset the card's dev server state from the modal

Autonomous job hangs

Symptoms. You clicked Run autonomous 30 minutes ago; the animated ring is still spinning; no progress in the modal.

Check.

Process actually running? Open Activity Monitor and look for the agent CLI process. If it's alive and using CPU, it's still working — just give it time on a complex card
Waiting for input? Rare, but the agent might have asked a clarifying question and be stuck. Open the card modal and check the chat; reply if needed
Network call stuck? Claude Code / Gemini / Codex talks to their respective APIs. If the network is flaky or the API is slow, the job stalls. Check the agent CLI's own debug output
Nothing works — kill it. Click Clear processing in the card modal header. This sets processingType = null and kills the process. You keep whatever state was already written (partial plan, partial commits)

Rebase conflict on merge

Symptoms. You click Merge; the card modal shows a Rebase conflict panel with a list of files.

Fix.

Click Auto-resolve with Claude for the easy path — it spawns a Claude session in the worktree, the agent reads the conflicting files, resolves them, and hands control back. Retry merge
Open the worktree in a terminal for manual resolution — use your normal git conflict workflow (git status, edit the files, git add, git rebase --continue). Then go back to Ideafy and click Retry merge

Conflicts usually mean another card merged something into main that overlaps with yours. This is normal parallel work — see Three features in parallel worktrees.

Supabase environment not configured (Team edition)

Symptoms. Team edition launches but doesn't show the sign-in button, or team features are missing.

Check.

Edition DMG. Did you install the Team DMG, not the Public one? Check Settings → About — it shows the edition
Config loaded. The Team DMG ships with Supabase config baked in. If you're self-hosting, verify your env vars are correct. Check the team-setup doc for the full env map
Network. Supabase has to be reachable. If you're on a restricted network, Supabase may be blocked

"Seat limit reached" when inviting

Symptoms. You're trying to invite a teammate; the app says "seat limit reached."

Fix.

Check current usage. Settings → Team → shows X / Y seats used
Remove inactive members to free seats without paying for more
Upgrade seats in the Stripe customer portal. Stripe prorates

Can't pull a card from the pool — "already pulled"

Symptoms. You click Pull on a pool card; you get a 409 Conflict error.

Reason. Someone else pulled it first. The atomic update only lets one puller win. The pool view may not have refreshed on your side yet.

Fix. Refresh the pool view. Pick a different card.

Conversation history looks weird after regenerating

Symptoms. You asked the agent to regenerate tests via save_tests. The Tests tab has new tests, but the checkboxes you ticked are gone.

Reason. Checkbox state is preserved per-task based on matching text. If the agent rewrote a test with even minor wording changes, the match fails and the new test starts unchecked.

Fix. Either accept it (go re-tick the boxes) or re-run with a prompt like "keep the test descriptions the same word-for-word; only add new tests at the end."

Still stuck

Check FAQ, then open an issue on the Ideafy repo. Include:

Your macOS version
Ideafy edition and version (Settings → About)
The card's display ID and what you were trying to do
Any error messages you saw

Prev: Three features in parallel worktrees Next: FAQ Up: User guide index