Troubleshooting

No diagnostics showing

Check your config exists:

ls -la .graphqlrc.yml

Verify document patterns match your files:

documents: "src/**/*.graphql" # Must match your file locations

Verify schema file exists:

ls -la schema.graphql  # Or whatever path is in your config

LSP not starting

VS Code: Check Output panel → “GraphQL Language Server” for errors.

Neovim: Run :LspLog to see LSP output.

Enable debug logging:

{
  "graphql-analyzer.debug.logLevel": "debug",
  "graphql-analyzer.server.env": {
    "RUST_LOG": "debug"
  }
}

Configuration not found

The tool searches for config files walking up the directory tree. Ensure your .graphqlrc.yml is at or above your workspace root.

Supported file names (in priority order):

1. .graphqlrc.yml / .graphqlrc.yaml
2. .graphqlrc.json
3. .graphqlrc.toml
4. .graphqlrc (YAML or JSON, auto-detected)
5. graphql.config.yml / graphql.config.yaml
6. graphql.config.json
7. graphql.config.toml
8. package.json with a "graphql" key (lowest priority fallback)

Not supported: graphql.config.js, graphql.config.ts

Schema loading errors

RUST_LOG=debug graphql validate

Look for schema loading errors in the output. Common causes:

• File path in config doesn’t match actual file location
• Glob pattern doesn’t match any files
• Remote URL is unreachable

Embedded GraphQL not working

The tag function must be imported from a recognized module:

// ✅ Works
import { gql } from "graphql-tag";

// ❌ Won't work — unknown module
import { gql } from "custom-unknown-module";

Add custom modules:

extensions:
  graphql-analyzer:
    extractConfig:
      modules:
        - "graphql-tag"
        - { name: "custom-module", identifier: "gql" }

Setting identifier constrains which export from the module is recognized as the GraphQL tag (matches @graphql-tools/graphql-tag-pluck semantics). Omit it to accept any default import from that module.

Performance issues

See Performance Tuning.

Quick fixes:

• Disable expensive rules in the LSP: noUnusedFields: off
• Check document patterns aren’t matching too many files
• Ensure node_modules isn’t included in document patterns

Reporting issues

File issues at GitHub Issues.

Include:

1. Your .graphqlrc.yml configuration
2. GraphQL Analyzer version
3. Editor and OS
4. Debug logs if applicable