From saleor-configurator
Diagnoses Saleor Configurator CLI deployment failures by exit code, JSON envelopes, and drill-down patterns. Use for error messages, partial failures, and reports.
npx claudepluginhub saleor/configuratorThis skill uses the workspace's default tool permissions.
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.
Parses JSON envelopes, exit codes, logs, errors, and results from Saleor Configurator CLI commands for automation scripts, workflows, and debugging failures.
Diagnoses common Shopify API errors (401, 403, 422, 429, GraphQL) with real responses, causes, and fixes like curl tests and scope reconfiguration.
Troubleshoots Outfitter Stack issues: Result validation/async/narrowing, MCP tool registration/invocation, CLI JSON output, exit codes.
Share bugs, ideas, or general feedback.
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.
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