troubleshooting

Diagnose Revenue Cloud build, deployment, data load, and toolchain failures.

Updated Sep 23, 2026
One-click install
npx skills add https://github.com/drgaciw/rlm-base-dev-fork --skill troubleshooting-drgaciw
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: troubleshooting
Source: https://github.com/drgaciw/rlm-base-dev-fork/tree/main/.cursor/skills/troubleshooting
Command: npx skills add https://github.com/drgaciw/rlm-base-dev-fork --skill troubleshooting-drgaciw

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a Revenue Cloud Foundations build pipeline fails — a CCI flow step errors out, an SFDMU data load misbehaves, a metadata deploy is blocked, or rating results look wrong — engineers waste hours hunting for the root cause. This Skill routes each failure symptom directly to the error catalog that owns it. ## Core Features & Use Cases - Failure Routing: Maps each of the 34 prepare_rlm_org flow steps to the correct diagnostic sub-file or domain skill, so you jump straight to the relevant error catalog. - Error Catalogs: Covers environment setup (validate_setup, org alias confusion, INVALID_AUTH_HEADER), SFDMU data loading (idempotency, composite keys), metadata deploy and permissions (PSG recalculation, source tracking), and pricing/rating errors (PUR activation, expression set row locks). - Live-Org Evidence Capture: Provides SOQL queries for RevenueTransactionErrorLog, AsyncOperationTracker, and order pricing state to capture async failure evidence before a data reset destroys it. - Use Case: A CCI flow fails at step 18 (prepare_rating) with a PUR activation error. The routing table points to pricing-and-config-errors.md, which explains the delete-rates-before-rating ordering fix. ## Quick Start Ask the agent to read the troubleshooting skill and diagnose why your prepare_rlm_org flow failed at a specific step, pasting the CCI error output.

Frequently Asked Questions about troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose a failed CCI flow step in a Salesforce build?▼

Run `cci task run validate_setup` first to rule out toolchain issues, then identify the failing step number from the CCI output. The skill's routing table maps each of the 34 `prepare_rlm_org` steps to the error catalog covering that category.

Why does my SFDMU data load create duplicate records on re-run?▼

Duplicates on re-run are caused by a missing or mismatched `$$` composite key column in the CSV, so the second load inserts instead of matching. Verify the CSV header matches the externalId fields exactly and run `validate_sfdmu_v5_datasets.py`.

Why does cci fail with INVALID_AUTH_HEADER but sf CLI works?▼

CumulusCI 4.10 parses `sf org display` for the access token, and sf CLI 2.13.0+ redacts it, so CCI sends a bogus header. Set `SF_TEMP_SHOW_SECRETS=true` in your environment; do not delete or recreate the org.

Can I use the same org alias for cci and sf CLI commands?▼

No, CCI and sf CLI maintain separate org registries with different alias formats. CCI uses short aliases like `beta` while sf CLI uses project-prefixed aliases like `rlm-base__beta`; the username always works with either tool.

Why does PUR activation fail with an effective period overlaps error?▼

Duplicate Draft PURs exist from re-running the plan without deleting first. Delete rates data, then rating data, then reload — always delete rates before rating due to the foreign key constraint.

How do I find the root cause of an async rating or preprocess failure?▼

Async failures leave their root cause in records, not stdout. Query `RevenueTransactionErrorLog` for the error message, `AsyncOperationTracker` for failed job types, and the order's `CalculationStatus` and `ValidationResult` before any data reset destroys the evidence.