Skip to content

🔧 Troubleshooting Guide

🎯 Overview

This comprehensive troubleshooting guide covers common issues encountered when working with the Continuum API Gateway, including authentication problems, permission errors, collection management issues, and performance concerns.

🔐 Authentication Issues

❌ Error 401: Unauthorized

Error Message: 

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

🔍 Possible Causes

  1. API Key is Missing or Malformed
  2. API Key Has Expired
  3. APP_KEY Changed After Key Generation
  4. Wrong Application Specified
  5. API Key Revoked

✅ Solutions

Check Header Format: 

# Correct format
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Common mistakes:
# ❌ Missing "Bearer " prefix
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# ❌ Extra spaces
Authorization: Bearer  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# ❌ Wrong header name
Auth: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Verify API Key Validity: 

# List your API keys to check expiration
GET /api/apiKeys:list
X-App: main
Authorization: Bearer {admin-api-key}

# Look for "expiresAt" field

Generate New API Key: 

POST /api/apiKeys:create
X-App: main
Authorization: Bearer {user-token}
Content-Type: application/json

{
  "role": {
    "name": "admin"
  },
  "expiresIn": "30d"
}

Check APP_KEY Configuration: 

# Ensure APP_KEY is set in environment
echo $APP_KEY

# If empty or changed, all existing keys are invalid
# Set it permanently in .env
APP_KEY=your-persistent-64-character-secret-key

Verify Correct Application: 

# List available applications
GET /api/applications:list
X-App: main

# Ensure X-App header matches key's application

❌ Error: "API key not valid for application"

Error Message: 

{
  "error": "Forbidden",
  "message": "API key not valid for application 'marketing-platform'"
}

🔍 Cause

Using an API key from one application to access another application.

✅ Solution

Create application-specific API keys:

# Create key for specific application
POST /api/apiKeys:create
X-App: marketing-platform
Authorization: Bearer {user-token-for-that-app}

{
  "role": {"name": "admin"},
  "expiresIn": "30d"
}

# Use with correct X-App header
GET /api/campaigns:list
X-App: marketing-platform
Authorization: Bearer {new-app-specific-key}

🛡️ Permission Issues

❌ Error 403: No Permissions

Error Message: 

{
  "error": "No permissions",
  "message": "Action 'create' on resource 'articles' is not allowed"
}

🔍 Possible Causes

  1. Role Lacks Required Permissions
  2. Filter Conditions Deny Access
  3. Field Restrictions Prevent Action
  4. Public Access Not Configured

✅ Solutions

Check Role Permissions: 

# Get role details with permissions
GET /api/roles:get?filterByTk=editor&appends=permissions
X-App: main
Authorization: Bearer {admin-api-key}

# Look for the specific resource and action

Check Filter Restrictions: 

# If you can list some records but not all:
# Check if filters are limiting access

# Example: Can only see own articles
{
  "filter": {
    "authorId": "{{ ctx.state.currentUser.id }}"
  }
}

# Solution: Use appropriate user context or request admin access

Create Key with Higher Privileges: 

# If current key has limited role
POST /api/apiKeys:create
X-App: main

{
  "role": {"name": "admin"},  # Higher privilege role
  "expiresIn": "7d"
}

Configure Public Access (if appropriate): 

# Grant public access to specific operations
# (This is configured system-wide, not per-request)

❌ Error: "Field access denied"

Error Message: 

{
  "error": "Forbidden",
  "message": "Access to field 'password' is denied"
}

🔍 Cause

Role's permissions don't include the requested field.

✅ Solution

Check Field Restrictions: 

# View permissions with field configurations
GET /api/roles:get?filterByTk={role-name}&appends=permissions
X-App: main

# Look for "fields" or "except" in permissions

Request Allowed Fields Only: 

# Good: Request only allowed fields
GET /api/users:list?fields=id,name,email
X-App: main

# Bad: Requesting restricted fields
GET /api/users:list?fields=id,name,password
X-App: main

📦 Collection Issues

❌ Error 404: Collection Not Found

Error Message: 

{
  "error": "Not Found",
  "message": "Collection 'articles' does not exist"
}

🔍 Possible Causes

  1. Collection Name Typo
  2. Collection Not Created Yet
  3. Wrong Application
  4. Collection Was Deleted

✅ Solutions

List Available Collections: 

GET /api/collections:list
X-App: main
Authorization: Bearer {api-key}

Check Collection Name: 

# Collection names are case-sensitive
# ✅ Correct
GET /api/blog_posts:list

# ❌ Wrong
GET /api/Blog_Posts:list
GET /api/blogPosts:list

Create Collection if Missing: 

POST /api/collections:create
X-App: main

{
  "name": "articles",
  "title": "Articles",
  "fields": [...]
}

❌ Error: "Field does not exist"

Error Message: 

{
  "error": "Bad Request",
  "message": "Field 'publishDate' does not exist in collection 'articles'"
}

🔍 Cause

Trying to access, filter, or sort by a field that doesn't exist.

✅ Solutions

List Collection Fields: 

GET /api/collections:get?filterByTk=articles&appends=fields
X-App: main

Check Field Name: 

# Common mistake: wrong field name
# ❌ publishDate
# ✅ publishedAt

GET /api/articles:list?sort=-publishedAt

Add Missing Field: 

POST /api/fields:create
X-App: main

{
  "collectionName": "articles",
  "name": "publishDate",
  "type": "date"
}

❌ Error: "Cannot modify system collection"

Error Message: 

{
  "error": "Forbidden",
  "message": "Cannot modify system collection 'users'"
}

🔍 Cause

Attempting to modify a built-in system collection.

✅ Solution

System collections (users, roles, permissions) have restricted modification:

  • ✅ CAN: Add custom fields
  • ❌ CANNOT: Delete collection or modify core fields
# ✅ Allowed: Add custom field
POST /api/fields:create
{
  "collectionName": "users",
  "name": "department",
  "type": "string"
}

# ❌ Not allowed: Delete system field
POST /api/fields:destroy
{
  "collectionName": "users",
  "name": "email"  # Core field
}

🔄 CRUD Operation Issues

❌ Error: "Validation failed"

Error Message: 

{
  "error": "Validation Error",
  "message": "Validation failed",
  "details": {
    "title": "Title is required",
    "email": "Email must be valid"
  }
}

🔍 Cause

Data doesn't meet validation requirements.

✅ Solution

Check Required Fields: 

# Get collection schema to see required fields
GET /api/collections:get?filterByTk=articles&appends=fields
X-App: main

# Include all required fields in request
POST /api/articles:create
{
  "title": "Required field",  # ✅ Included
  "content": "..."
}

Validate Data Types: 

# ❌ Wrong type
{
  "price": "nine ninety-nine"  # Should be number
}

# ✅ Correct type
{
  "price": 9.99
}

❌ Error: "Unique constraint violation"

Error Message: 

{
  "error": "Conflict",
  "message": "Duplicate value for unique field 'email'"
}

🔍 Cause

Trying to create/update with a value that already exists for a unique field.

✅ Solutions

Check Existing Records: 

# Search for existing record
GET /api/users:list?filter={"email":"user@example.com"}
X-App: main

Update Instead of Create: 

# If record exists, update it
POST /api/users:update?filterByTk=1
{
  "name": "Updated Name"
}

Use Different Value: 

# Use unique value
POST /api/users:create
{
  "email": "unique.email@example.com"
}

❌ Error: "Foreign key constraint failed"

Error Message: 

{
  "error": "Bad Request",
  "message": "Foreign key constraint failed for field 'authorId'"
}

🔍 Cause

Referenced record doesn't exist (e.g., author with ID 999 doesn't exist).

✅ Solutions

Verify Referenced Record Exists: 

# Check if user exists
GET /api/users:get?filterByTk=999
X-App: main

# If not, use valid user ID
POST /api/articles:create
{
  "title": "Article",
  "authorId": 5  # Existing user ID
}

Create Referenced Record First: 

# Create user first
POST /api/users:create
{
  "name": "New Author",
  "email": "author@example.com"
}
# Response: {"data": {"id": 10, ...}}

# Then create article
POST /api/articles:create
{
  "title": "Article",
  "authorId": 10
}

🌐 Multi-App Issues

❌ Error: "Application not found"

Error Message: 

{
  "error": "Not Found",
  "message": "Application 'marketing-platform' not found"
}

🔍 Possible Causes

  1. Application Name Typo
  2. Application Doesn't Exist
  3. Application Not Started

✅ Solutions

List Available Applications: 

GET /api/applications:list
X-App: main
Authorization: Bearer {api-key}

Check Application Name: 

# Application names are case-sensitive and exact
X-App: marketing-platform  # ✅ Correct
X-App: Marketing-Platform  # ❌ Wrong case
X-App: marketing platform  # ❌ Space

Create Application if Missing: 

POST /api/applications:create
X-App: main

{
  "name": "marketing-platform",
  "displayName": "Marketing Platform",
  "options": {
    "autoStart": true
  }
}

❌ Error: "Application initialization failed"

Error Message: 

{
  "error": "Internal Server Error",
  "message": "Failed to initialize application 'my-app'"
}

🔍 Possible Causes

  1. Database Connection Error
  2. Plugin Loading Failure
  3. Configuration Issue
  4. Insufficient Resources

✅ Solutions

Check Application Status: 

GET /api/applications:get?filterByTk=my-app&appends=errorLog
X-App: main

Review Server Logs: 

# Check application server logs for detailed error
tail -f /var/log/continuum/app.log

Restart Application: 

POST /api/applications:start?filterByTk=my-app
X-App: main

Check Database Configuration: 

# Verify database credentials and connectivity
# Check database exists and is accessible

⚡ Performance Issues

❌ Slow Query Response

Symptom: API requests taking > 1 second

🔍 Possible Causes

  1. Missing Indexes
  2. Fetching Too Much Data
  3. N+1 Query Problem
  4. Complex Filters
  5. No Caching

✅ Solutions

Add Indexes: 

# Identify slow queries from logs
# Add indexes to frequently filtered/sorted fields

# In database:
CREATE INDEX idx_articles_status ON articles(status);
CREATE INDEX idx_articles_published_at ON articles(published_at);

Use Pagination: 

# ❌ Bad: Fetch all records
GET /api/articles:list?paginate=false

# ✅ Good: Paginate
GET /api/articles:list?page=1&pageSize=20

Select Only Needed Fields: 

# ❌ Bad: All fields
GET /api/articles:list

# ✅ Good: Specific fields
GET /api/articles:list?fields=id,title,createdAt

Optimize Relationship Loading: 

# ❌ Bad: Loading too many relations
GET /api/articles:list?appends=author,comments,tags,category,relatedPosts

# ✅ Good: Only needed relations
GET /api/articles:list?appends=author

Use Efficient Filters: 

# ❌ Slow: LIKE with leading wildcard
GET /api/articles:list?filter={"title":{"$like":"%search%"}}

# ✅ Faster: Exact match or indexed field
GET /api/articles:list?filter={"status":"published"}

🔧 General Debugging

📊 Enable Debug Logging

# Set environment variable
DEBUG=api:*

# Restart server
# Check logs for detailed request/response info

🔍 Test with cURL

Isolate issues by testing with cURL:

# Full verbose output
curl -v \
  -H "X-App: main" \
  -H "Authorization: Bearer {api-key}" \
  https://your-domain.com/api/articles:list

# Specific checks:
# - HTTP status code
# - Response headers
# - Response body
# - Request headers sent

🧪 Test in Different Environments

# Development
X-App: dev-environment

# Staging
X-App: staging-environment

# Production
X-App: main

# If works in one but not another, it's environment-specific

📝 Check API Documentation

# Access Swagger UI
https://your-domain.com/admin/settings/api-doc/documentation

# Verify:
# - Endpoint exists
# - Request format
# - Required parameters
# - Expected responses

📞 Getting Help

🔍 Before Requesting Support

Gather the following information:

  1. Error Message: Full error response
  2. Request Details: 
    Method: POST
URL: /api/articles:create
Headers: X-App: main, Authorization: Bearer ...
Body: {...}
  3. Application Context: Which app, environment
  4. API Key Role: What permissions the key has
  5. Recent Changes: Schema changes, permission updates
  6. Server Logs: Relevant log entries

📊 Diagnostic Endpoints

# System health
GET /api/health
X-App: main

# Current user context
GET /api/auth:check
X-App: main
Authorization: Bearer {api-key}

# Application info
GET /api/applications:get?filterByTk=main
X-App: main
  • API Gateway: Overall architecture
  • Authentication: API key management
  • Permissions: Access control configuration
  • Best Practices: Optimization and security guidelines

Note: Most issues can be resolved by checking authentication, permissions, and request format. When in doubt, consult the Swagger documentation and verify with admin credentials.