Troubleshooting

Setup Issues

Symptom	Solution
`pnpm install` fails	Verify Node.js 22+ (`node --version`) and pnpm 9+ (`pnpm --version`)
Database connection error	Check PostgreSQL is running and `DATABASE_URL` in `.env` is correct
pgvector extension missing	Run `psql mify -c "CREATE EXTENSION IF NOT EXISTS vector;"`
Prisma migration fails	Run `pnpm --filter @mify/api prisma:migrate deploy` to apply pending migrations. If the database is a fresh dev instance, run `pnpm --filter @mify/api prisma:migrate dev` to regenerate.

Port	Service	Check Command
3006	Web UI	`lsof -i :3006` (Mac/Linux) or `netstat -ano \| findstr :3006` (Windows)
3010	API Server	`lsof -i :3010` or `netstat -ano \| findstr :3010`
5432	PostgreSQL	Check PostgreSQL service is running

Verify both services are running:

# API health
curl http://localhost:3010/health
# Expected: { "status": "ok" }

# Web UI
# Open http://localhost:3006 — should load the MIFY interface

Symptom	Cause	Solution
”No trigger” error	Missing trigger node	Add a Manual Trigger, Webhook, or Schedule trigger
”Cycle detected” error	Workflow has a loop	Remove the edge that creates the cycle (MIFY requires DAGs)
“Provider not configured”	Missing API key	Add your provider key in Settings → Credentials
Execution hangs	Node waiting for input	Check if a Pause/HITL node needs approval

Error	Provider	Solution
`401 Unauthorized`	OpenAI, Anthropic	Check API key in Settings → Credentials
`429 Rate Limited`	Any	Wait and retry. Check quota in Settings → Usage
`Connection refused`	Ollama	Verify Ollama is running (`ollama serve`)
`Model not found`	Ollama	Pull the model first: `ollama pull phi3:mini`
Timeout	Any	Increase timeout in node settings or check network

View execution details at /runs:

Symptom	Solution
”Invalid JSON”	Verify you copied the complete workflow export
Nodes show as “Opaque”	These nodes don’t have MIFY equivalents — they delegate to the original platform
Missing credentials	Imported workflows don’t include secrets — re-add API keys in MIFY

Cause	Solution
Large batch processing	Reduce concurrency in batch settings
N+1 database queries	Check SQL query budget in observability settings
Cold start on AI providers	First call to a provider may be slow; subsequent calls are faster

Cause	Solution
Large document ingestion	Process documents in smaller batches
Many concurrent executions	Reduce parallel execution limit

Symptom	Solution
”Command not found”	Install the agent CLI (`claude` or `codex`) and verify it’s in PATH
”Git not configured”	Run `git config --global user.name` and `user.email`
”Port 3020 in use”	Another home runtime instance is running. Stop it first.
”RunAlreadyActiveError”	Cancel the existing run before starting a new one

Symptom	Solution
Agent waiting for input	Send input via the terminal UI
Trust prompt appears	Accept the workspace trust prompt in the agent
Idle timeout	Agent timed out (30 min default). Restart the run.