Troubleshooting

Troubleshooting

Common issues and solutions for DO Manager.

---

API & Authentication Issues

"Failed to fetch from Cloudflare API"

Causes:

• Incorrect ACCOUNT_ID
• API token missing required permissions

Solutions:

1. Verify ACCOUNT_ID is correct (find it in your dashboard URL: dash.cloudflare.com/ACCOUNT_ID/...)
2. Ensure API token has Workers Scripts Read permission
3. If using Global API Key, verify the email is correct

Test your API token:

curl -X GET "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/workers/scripts" \
  -H "Authorization: Bearer ${API_KEY}"

"Authentication loop" or "Access denied"

Causes:

• Misconfigured Cloudflare Access settings
• Incorrect TEAM_DOMAIN or POLICY_AUD

Solutions:

1. Check TEAM_DOMAIN includes https:// (e.g., https://yourteam.cloudflareaccess.com)
2. Verify POLICY_AUD matches your Access application's AUD tag exactly
3. Ensure your email/identity is included in the Access policy
4. Clear browser cookies and try again

"401 Unauthorized"

Solutions:

1. Re-authenticate via Cloudflare Access
2. Check if your Access session has expired
3. Verify the Access application is configured for your domain

---

Namespace Issues

"No namespaces discovered"

Causes:

• No Durable Objects deployed in your account
• System namespaces are being filtered

Solutions:

1. Deploy a Worker with Durable Objects first
2. System namespaces (kv-manager_*, d1-manager_*, do-manager_*) are filtered by default
3. Add namespaces manually if auto-discovery doesn't work

"Admin hook not configured"

Causes:

• Admin hook methods not added to DO class
• Endpoint URL not set in namespace settings
• Worker not deployed

Solutions:

1. Install do-manager-admin-hooks NPM package in your Worker
2. Call this.handleAdminRequest(request) in your DO's fetch method
3. Set the Admin Hook Endpoint URL in namespace settings
4. Redeploy your Worker after adding admin hooks

---

Instance Issues

"Clone instance creates empty instance"

Causes:

• Admin hooks using incorrect export/import format

Solutions:

1. Ensure export returns:

   { "data": {...}, "exportedAt": "...", "keyCount": N }

2. Ensure import accepts:

   { "data": {...} }

3. Use the do-manager-admin-hooks NPM package which handles this automatically

"Instance not found" or "Failed to connect"

Solutions:

1. Verify the instance ID is correct
2. Check if the Durable Object still exists
3. Ensure admin hooks are deployed and accessible
4. Test the admin endpoint directly:

   curl https://your-worker.workers.dev/admin/list

"Storage operation failed"

Solutions:

1. Check Worker logs in Cloudflare dashboard
2. Verify the DO has the correct admin hook endpoints
3. For SQLite DOs, ensure the SQL is valid
4. Check for storage quota limits (10GB per DO)

---

Docker Issues

Container Won't Start

Check logs:

docker logs do-manager

Common causes:

• Missing environment variables
• Port already in use

Solutions:

1. Ensure all required environment variables are set:
   • ACCOUNT_ID
   • API_KEY
   • TEAM_DOMAIN
   • POLICY_AUD
2. Try a different port: -p 8788:8787

"Connection refused" when accessing localhost

Solutions:

1. Verify container is running: docker ps
2. Check the port mapping is correct
3. On Docker Desktop, ensure the container has network access

Container exits immediately

Solutions:

1. Check logs for error messages
2. Verify environment variables are properly escaped
3. Try running interactively: docker run -it --rm writenotenow/do-manager:latest

---

SQL Console Issues

"SQL execution failed"

Causes:

• Invalid SQL syntax
• Table doesn't exist
• Trying SQL on KV-backed DO

Solutions:

1. Verify the namespace is SQLite-backed (not KV)
2. Check SQL syntax is valid SQLite
3. Use SELECT name FROM sqlite_master WHERE type='table' to list tables

"No tables found"

Solutions:

1. The DO may not have created any tables yet
2. Tables are created on first use — interact with the DO to initialize
3. Check if using the correct instance

---

Backup & Restore Issues

"Backup failed"

Causes:

• R2 bucket not configured
• Export endpoint not working

Solutions:

1. Verify R2 bucket do-manager-backups exists
2. Check R2 binding in wrangler.toml
3. Test export endpoint directly

"Restore failed"

Solutions:

1. Verify the backup exists in R2
2. Check import endpoint is working
3. Ensure data format is compatible

---

Performance Issues

Slow page loads

Solutions:

1. Reduce the number of instances/keys displayed
2. Use search/filter to narrow results
3. Check Cloudflare Worker CPU limits

Operations timing out

Solutions:

1. Break batch operations into smaller batches
2. Check Worker timeout limits (30s for Workers)
3. For large exports, consider paginating

---

Development Issues

Local development not working

Solutions:

1. Ensure both servers are running:
   • Frontend: npm run dev (port 5173)
   • Worker: npx wrangler dev --config wrangler.dev.toml --local (port 8787)
2. Initialize local D1:

   npx wrangler d1 execute do-manager-metadata-dev --local --file=worker/schema.sql

"Module not found" errors

Solutions:

1. Run npm install to install dependencies
2. Delete node_modules and reinstall:

   rm -rf node_modules
   npm install

TypeScript errors

Solutions:

1. Run npm run typecheck to see all errors
2. Ensure TypeScript version matches project (5.9.3)

---

Getting Help

If your issue isn't listed here:

1. Search Issues: GitHub Issues

2. Email Support: admin@adamic.tech

When reporting issues, include:

• DO Manager version
• Deployment method (Workers or Docker)
• Error messages from browser console or Worker logs
• Steps to reproduce