GraphQL Error Response Format #

{
  "errors": [
    {
      "message": "Authentication failed: Invalid JWT token",
      "locations": [],
      "path": [],
      "extensions": {
        "code": "UNAUTHORIZED",
        "details": "Token has expired",
        "timestamp": "2024-01-15T14:30:00Z",
        "hint": "Generate a new JWT token using the KeyGenerator console application"
      }
    }
  ]
}

Common Error Codes #

• UNAUTHORIZED: Authentication failed or JWT token invalid
• FORBIDDEN: Insufficient permissions for requested operation
• VALIDATION_ERROR: Invalid query syntax or arguments
• INTERNAL_ERROR: Server or M-Files API error
• SCHEMA_ERROR: Schema generation or refresh failed
• VAULT_CONNECTION_ERROR: Unable to connect to specified vault

Error Response Examples #

Authentication Error #

{
  "errors": [
    {
      "message": "Authentication failed: JWT token is required",
      "extensions": {
        "code": "UNAUTHORIZED",
        "hint": "Include X-API-Key header with valid JWT token"
      }
    }
  ]
}

Vault Connection Error #

{
  "errors": [
    {
      "message": "Failed to connect to vault 'Production'",
      "extensions": {
        "code": "VAULT_CONNECTION_ERROR",
        "details": "Connection timeout to M-Files server",
        "vaultName": "Production"
      }
    }
  ]
}

Query Validation Error #

{
  "errors": [
    {
      "message": "Cannot query field 'invalidField' on type 'ProductionDocument'",
      "locations": [{ "line": 3, "column": 5 }],
      "extensions": { "code": "VALIDATION_ERROR" }
    }
  ]
}

Troubleshooting #

Common Issues and Solutions #

Schema Generation Issues #

Problem: “No vault connections configured”

• Solution: Verify VaultConnections array in appsettings.json is properly configured (See the Configuration page for more details.)
• Check: Each vault connection has all required properties (VaultName, NetworkAddress, etc.)

Problem: “Failed to load schema for vault”

• Solution: Verify TRAPI service is running and accessible
• Check: Network connectivity between GRAPI and TRAPI services
• Verify: Vault connection parameters are correct

Query Execution Issues #

Problem: “Cannot query field ‘fieldName’ on type ‘ObjectType’”

• Solution: Field doesn’t exist in the generated schema
• Check: Use GraphQL Playground to explore available fields
• Action: Refresh schema if M-Files vault structure changed

Problem: Slow query performance

• Solutions:
• Reduce the number of requested fields
• Add more specific filtering conditions
• Use pagination (limit/offset)
• Avoid excessive nested object resolution

Authentication Issues #

Problem: “JWT token is required”

• Solution: Include X-API-Key header with valid JWT token
• Check: Token is not expired
• Verify: Token was generated with correct private key

Problem: “Authentication failed: Invalid JWT token”

• Solution: Generate new JWT token using KeyGenerator
• Check: Public key in configuration matches private key used for token generation

Multi-Vault Issues #

Problem: “Vault ‘VaultName’ not found”

• Solution: Verify vault name matches exactly with configuration
• Check: Case sensitivity in vault names
• Action: Use refreshAll mutation to reload vault configurations

Performance Monitoring #

Query Analysis #

Use GraphQL Playground to analyze query performance:

1. Enable Tracing: Add ?trace=true to GraphQL endpoint URL
2. Review Execution Plan: Check resolver execution times in response
3. Analyze Field Selection: Verify only necessary fields are requested
4. Monitor Memory Usage: Watch for memory leaks in complex queries

Support Resources #

• GraphQL Playground: Please refer to the Nitro documentation.
• GraphQL Documentation: Refer to GraphQL specification for query syntax.