---
title: "Errors & Troubleshooting"
description: "## 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…"
url: "https://extensionkit.unitfly.com/documentation/grapi-errors-troubleshooting/"
updated: "2026-01-23"
category: GRAPI Wiki and User Guide
---

# Errors & Troubleshooting

## 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](https://extensionkit.unitfly.com/documentation/grapi-configuration/) 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](https://chillicream.com/docs/nitro).
- **GraphQL Documentation**: Refer to [GraphQL specification](https://graphql.org/learn/introduction/) for query syntax.