Nexus Troubleshooting

Diagnosis guides for common Nexus project management issues.

Project not found

Symptoms:

GET /v1/projects/:id returns 404
Other endpoints return “Project not found”

Possible causes:

1. Project was deleted

Soft-deleted projects are immediately inaccessible.

Diagnosis:

curl "https://api.solenoid.systems/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

If project missing from list, it was deleted.

Fix: Create a new project. Deleted projects are not restorable.

2. Wrong project ID

Typo or copy-paste error in project ID.

Diagnosis: Verify ID format starts with proj_ and matches exact ID from list response.

Fix: Copy project ID directly from GET /v1/projects response.

3. API key scoped to different user

Using API key from different account.

Diagnosis: Check API key owner via /v1/keys/verify endpoint.

Fix: Use API key from correct account.

Cannot delete default project

Symptoms:

DELETE /v1/projects/:id returns 403 Forbidden
Error message: “Cannot delete default project”

Cause: Default project is the only active project in your account.

Fix:

Create at least one other project:

curl -X POST "https://api.solenoid.systems/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'

Now delete default project:

curl -X DELETE "https://api.solenoid.systems/v1/projects/proj_default..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Why this exists: Prevents API keys from breaking when all projects are removed. At least one project must exist.

Resources still visible after project delete

Symptoms:

Deleted project but resources (flags, monitors, etc.) still appear in other endpoints
Project overview shows non-zero counts after deletion

Cause: Resource cleanup is asynchronous. Full purge happens in background with retry semantics.

Expected behavior:

Project becomes inaccessible immediately (404 on all operations)
Resources purged across all 8 product workers over next few minutes
Eventual consistency — some workers may take longer

Diagnosis:

Wait 5 minutes, then check project overview:

# This should return 404 if project deleted
curl "https://api.solenoid.systems/v1/projects/proj_abc123.../overview" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fix: Wait for async cleanup to complete. Retry checks in delayed products. No manual intervention needed.

Typical timeline:

t=0s: Project soft-deleted, immediately inaccessible
t=5s: Queue message dispatched to all product workers
t=10-60s: Product workers purge resources
t=60s+: All resources fully cleaned up

Slug collision on project creation

Symptoms:

Created project but slug is “production-2” instead of “production”
Unexpected numeric suffix in slug

Cause: Another project already exists with slug “production”. Nexus auto-resolves by appending -N suffix.

Expected behavior:

First project: slug = “production”
Second project: slug = “production-2”
Third project: slug = “production-3”
After 10 attempts: fallback to UUID

Fix: This is normal. Slugs are auto-generated and must be unique. Use the returned slug value, not the name.

Example:

curl -X POST "https://api.solenoid.systems/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Production"}'

# Response:
# {
#   "id": "proj_abc123...",
#   "name": "Production",
#   "slug": "production-2",  <-- Auto-incremented
#   ...
# }

If you need specific slug: Delete existing projects with conflicting slugs first, then recreate.

Project overview shows stale counts

Symptoms:

Created/deleted resources but project overview counts don’t update
Resource counts inconsistent with list endpoints

Cause: Project overview is cached for 5 minutes in KV to reduce RPC fan-out load.

Diagnosis:

Check cache freshness:

curl "https://api.solenoid.systems/v1/projects/proj_abc123.../overview" \
  -H "Authorization: Bearer YOUR_API_KEY" -i

Look for X-Cache: HIT or X-Cache: MISS header (if exposed).

Fix:

Wait 5 minutes — cache expires automatically
Force refresh — delete/update project to invalidate cache
Use product-specific endpoints — always return fresh data (no cache)

Example:

# Stale overview count
curl ".../v1/projects/proj_123/overview"  # Shows flags: 5

# Fresh product endpoint
curl ".../v1/gate"  # Shows 7 flags (correct)

# Wait 5 minutes, retry overview
curl ".../v1/projects/proj_123/overview"  # Now shows flags: 7

Why cache exists: Prevents excessive RPC fan-out to all 8 product workers on every dashboard poll.

API key not scoped to expected project

Symptoms:

Created resources appear in wrong project
Resources missing from expected project

Cause: API key’s project_id binding points to different project than expected.

Diagnosis:

Verify API key’s project binding:

curl "https://api.solenoid.systems/v1/keys/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes project_id field showing which project this key targets.

Fix:

Create new API key scoped to correct project:

curl -X POST "https://api.solenoid.systems/v1/keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -d '{
    "name":"Staging Key",
    "project_id":"proj_staging123..."
  }'

Update existing key (if supported in future):

# Not yet implemented — create new key instead

Workaround: Create separate API keys per project. Use environment variables to switch keys.

Pagination cursor invalid

Symptoms:

GET /v1/projects?cursor=... returns 400 validation error
Error message: “Invalid cursor”

Cause: Cursor expired, corrupted, or from different query.

Fix: Start pagination from beginning (omit cursor parameter):

curl "https://api.solenoid.systems/v1/projects?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Prevention: Don’t store cursors long-term. Use cursors immediately in next request.

Project creation slow or times out

Symptoms:

POST /v1/projects takes >5 seconds
Request times out before completion

Cause: Database contention or slug collision retry loop.

Diagnosis:

Check for high project creation rate:

# List recent projects
curl "https://api.solenoid.systems/v1/projects?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

If many projects created in last minute, database may be under load.

Fix:

Implement exponential backoff
Reduce concurrent project creation rate
Retry failed requests after delay

Typical latency:

p50: <200ms
p95: <500ms
p99: <1s

If consistently >1s, contact support.

General Debugging Checklist

Verify API key validity — Check authorization header format
Check project exists — Use GET /v1/projects to list all active projects
Confirm project not deleted — Deleted projects return 404 immediately
Inspect cache — Project overview cached 5 minutes
Review rate limits — Implement exponential backoff
Check error responses — All errors include code and message fields
Monitor async cleanup — Resource purge takes up to 60 seconds after project deletion

Getting Help

If issue persists after following these guides:

Check error code in Errors documentation
Review API reference for correct request format
Contact support with request ID from X-Request-ID response header

Next steps

API Reference — Full endpoint documentation
Errors — Error code reference