Troubleshooting#

Common issues and how to resolve them.

OAuth Errors#

"Invalid redirect URI"#

The redirect URI in your OAuth request doesn't match any registered URI.

Fix: Ensure the redirect URI in your app exactly matches one in Settings > OAuth Clients. URIs must match protocol, host, port, and path.

"Invalid client ID"#

The client ID doesn't exist or was deleted.

Fix: Verify the client ID in Settings > OAuth Clients. If it was deleted, register a new client.

"PKCE code verifier mismatch"#

The code verifier sent during token exchange doesn't match the code challenge from authorization.

Fix: The code verifier wasn't stored correctly between authorization redirect and callback. If using the SDK, call handleRedirectCallback() in the same browser session that initiated login.

"DPoP proof invalid"#

The DPoP proof header is missing, malformed, or signed with the wrong key.

Fix: If using the SDK, this is handled automatically. If implementing manually, ensure:

• The DPoP header contains a valid JWT
• The JWT is signed with the same key used during token exchange
• The htm and htu claims match the request method and URL

GraphQL Errors#

"Cannot query field X on type Y"#

The field doesn't exist on the queried type.

Fix: Check your query against the schema in GraphiQL. Common causes:

• Typo in field name
• Field exists on a different type (use inline fragments for unions)
• Lexicon wasn't imported yet

"Variable $X of type Y used in position expecting Z"#

Type mismatch between your variable declaration and how it's used.

Fix: Check variable types in your query definition. Common issues:

• Using String instead of DateTime for date fields
• Missing ! for required variables
• Using wrong scalar type

"Record not found"#

The record you're trying to update or delete doesn't exist.

Fix: Verify the record key (rkey). Query for the record first to confirm it exists.

Jetstream Issues#

Records not appearing after creation#

Records created via mutation should appear immediately due to optimistic indexing. If they don't:

Check:

1. Was the mutation successful? Check the response for errors.
2. Is the record in the user's PDS? Use goat repo get to verify.
3. Is Jetstream connected? Check the logs for connection errors.

Old records missing#

Records created before you deployed Quickslice won't appear until backfilled.

Fix: Trigger a backfill from the admin UI or wait for the scheduled backfill to complete.

Backfill stuck or slow#

Check:

1. Memory usage - backfill is memory-intensive. See Deployment Guide for tuning.
2. Network connectivity to PDS endpoints
3. Logs for specific PDS errors

Database Issues#

"Database is locked"#

SQLite can't acquire a write lock. Caused by long-running queries or concurrent access.

Fix:

• Ensure only one Quickslice instance writes to the database
• Check for stuck queries in logs
• Restart the service if needed

Disk space full#

SQLite needs space for WAL files and vacuuming.

Fix: Expand your volume. See your hosting platform's documentation.

Debugging Tips#

Check if records are being indexed#

Query for recent records:

query {
  xyzStatusphereStatus(first: 5, sortBy: [{ field: indexedAt, direction: DESC }]) {
    edges {
      node {
        uri
        indexedAt
      }
    }
  }
}

Verify OAuth is working#

Query the viewer:

query {
  viewer {
    did
    handle
  }
}

Returns null if not authenticated. Returns user info if authenticated.

Inspect the GraphQL schema#

Use GraphiQL at /graphiql to explore types, queries, and mutations. The Docs panel shows all fields and types.

Check Lexicon registration#

Use the MCP endpoint or admin UI to list registered Lexicons:

query {
  __schema {
    types {
      name
    }
  }
}

Look for types matching your Lexicon NSIDs (e.g., XyzStatusphereStatus).

FAQ#

"Why aren't my records showing up?"#

1. Just created? Should appear immediately. Check mutation response for errors.
2. Created before deployment? Needs backfill. Trigger from admin UI.
3. Different Lexicon? Ensure the Lexicon is registered in your instance.

"Why is my mutation failing?"#

1. 401 Unauthorized? Token expired or invalid. Re-authenticate.
2. 403 Forbidden? Trying to modify another user's record.
3. 400 Bad Request? Check input against Lexicon schema. Required fields missing?

"How do I check what Lexicons are loaded?"#

Go to Settings in the admin UI, or query via MCP:

claude mcp add --transport http quickslice https://yourapp.slices.network/mcp
# Then ask: "What lexicons are registered?"