Configurator Troubleshooting

Overview

This skill provides a systematic framework for diagnosing and fixing Configurator CLI failures. It covers error classification by exit code, drill-down patterns for partial failures, common error patterns with solutions, and a structured reporting format.

When to Use

• Any CLI command fails with a non-zero exit code
• User reports error messages from configurator
• Deployment completed with partial failures
• Debugging GraphQL errors or reference issues
• When NOT looking for the deployment workflow -- use configurator-workflow instead
• When NOT looking for JSON envelope structure -- use agent-output-parsing instead

Error Analysis Framework

Step 1: Gather Context via JSON Envelope

The fastest way to diagnose is to parse the JSON envelope output:

# Validate config (no network needed)
pnpm dlx @saleor/configurator validate --json 2>/dev/null | jq '.'

# Get diff details for specific entity
pnpm dlx @saleor/configurator diff --entity "Type/name" --json 2>/dev/null | jq '.'

# Check last deployment report
ls -t deployment-report-*.json 2>/dev/null | head -1 | xargs cat | jq '.'

Step 2: Classify by Exit Code

Code	Name	Diagnosis
0	SUCCESS	No error (user may have questions about output)
1	UNEXPECTED	Check .errors and .logs in envelope
2	AUTHENTICATION	Invalid token, expired credentials, wrong URL
3	NETWORK	Connection refused, DNS failure, timeout
4	VALIDATION	YAML syntax, schema violations, missing fields
5	PARTIAL_FAILURE	Some entities failed - drill down with --entity
6	DELETION_BLOCKED	--fail-on-delete triggered
7	BREAKING_BLOCKED	--fail-on-breaking triggered

Step 3: Drill Down for Partial Failures (Exit Code 5)

# 1. Parse failed entities from envelope
OUTPUT=$(pnpm dlx @saleor/configurator deploy --json 2>/dev/null)
echo "$OUTPUT" | jq -r '.errors[] | "\(.entity): \(.message)"'

# 2. Drill into specific entity
pnpm dlx @saleor/configurator diff --entity "Categories/electronics" --json 2>/dev/null | jq '.result'

# 3. Check field-level differences
pnpm dlx @saleor/configurator diff --entity-type "Categories" --json 2>/dev/null | jq '.result.operations[]'

Step 4: Apply Fix Based on Error Pattern

See the Common Error Patterns section below for specific solutions.

Exit Code Decision Tree

exitCode == 0 --> Success, no action needed
exitCode == 1 --> Read error message, check logs array
exitCode == 2 --> Credentials issue:
                    - Regenerate token in Saleor Dashboard
                    - Verify URL ends with /graphql/
                    - Check HTTPS
exitCode == 3 --> Network issue:
                    - Verify URL is reachable
                    - Check DNS, firewall, VPN
exitCode == 4 --> Config validation failed:
                    - Run: validate --json
                    - Fix errors in config.yml
exitCode == 5 --> Partial failure:
                    - Parse errors array for failed entities
                    - Use --entity drill-down to inspect
                    - Fix and redeploy
exitCode == 6 --> Deletions blocked:
                    - Review deletions in diff output
                    - Remove entities from config or remove --fail-on-delete
exitCode == 7 --> Breaking changes blocked:
                    - Review breaking changes
                    - Remove --fail-on-breaking or accept changes

Common Error Patterns

Authentication (Exit Code 2)

Diagnosis: Token is invalid, expired, or has insufficient permissions.

Fix:

1. Verify SALEOR_URL ends with /graphql/ and uses HTTPS
2. Regenerate token in Saleor Dashboard
3. Check token permissions (needs MANAGE_* permissions)

Test authentication:

curl -X POST $SALEOR_URL \
  -H "Authorization: Bearer $SALEOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ shop { name } }"}'

Validation (Exit Code 4)

Diagnosis: Config file has schema errors.

Fix:

# Get exact errors
pnpm dlx @saleor/configurator validate --json 2>/dev/null | jq '.result.errors[] | "\(.path): \(.message)"'

Duplicate Entity

Error: Product with slug "my-product" already exists

Fix:

1. Run introspect to pull current state
2. Modify existing entity instead of creating
3. Use a different slug

Invalid Reference

Error: ProductType "NonExistent" not found

Fix:

1. Check exact spelling of the referenced type
2. Ensure the referenced entity is defined in config.yml
3. Entity types must be deployed before entities that reference them

Rate Limiting

Fix: The CLI has built-in rate limiting. If still hitting limits:

1. Reduce GRAPHQL_MAX_CONCURRENCY (default: 4)
2. Deploy in smaller batches using --include

Diagnostic Commands

# 1. Validate config locally (no network)
pnpm dlx @saleor/configurator validate --json 2>/dev/null

# 2. Drill into specific entity
pnpm dlx @saleor/configurator diff --entity "Type/name" --json 2>/dev/null

# 3. Check last deployment report
ls -la deployment-report-*.json

# 4. Full diff
pnpm dlx @saleor/configurator diff --json 2>/dev/null

# 5. Test authentication
curl -X POST $SALEOR_URL \
  -H "Authorization: Bearer $SALEOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ shop { name } }"}'

Troubleshooting Report Format

When diagnosing issues, structure your findings as:

ERROR IDENTIFIED
Type: [Error Type] (Exit Code [N])
Message: [Error Message]

ROOT CAUSE
[Explanation of what caused the error]

SOLUTION
Step 1: [First action]
Step 2: [Second action]

VERIFICATION
[Command to verify the fix]

PREVENTION
- [Best practice 1]
- [Best practice 2]

Related Skills

• configurator-workflow - Full deployment workflow sequence
• agent-output-parsing - JSON envelope structure and parsing
• configurator-cli - Complete command reference and flags