Terminal
Terminal/Skill
Steps to diagnose failed Configurator CLI runs by exit code, partial deployment failures and error messages.
By Saleor
Works with
npx skills add saleor/configurator --skill configurator-troubleshootThis 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.
configurator-workflow insteadagent-output-parsing insteadThe 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 '.'
| 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 |
# 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[]'
See the Common Error Patterns section below for specific solutions.
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
Diagnosis: Token is invalid, expired, or has insufficient permissions.
Fix:
SALEOR_URL ends with /graphql/ and uses HTTPSMANAGE_* permissions)Test authentication:
curl -X POST $SALEOR_URL \
-H "Authorization: Bearer $SALEOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "{ shop { name } }"}'
Diagnosis: Config file has schema errors.
Fix:
# Get exact errors
pnpm dlx @saleor/configurator validate --json 2>/dev/null | jq '.result.errors[] | "\(.path): \(.message)"'
Error: Product with slug "my-product" already exists
Fix:
introspect to pull current stateError: ProductType "NonExistent" not found
Fix:
Fix: The CLI has built-in rate limiting. If still hitting limits:
GRAPHQL_MAX_CONCURRENCY (default: 4)--include# 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 } }"}'
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]
configurator-workflow - Full deployment workflow sequenceagent-output-parsing - JSON envelope structure and parsingconfigurator-cli - Complete command reference and flags