troubleshooting

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

5|3|Updated Sep 9, 2026
One-click install
npx skills add https://github.com/SalesforceLabs/revenue-cloud-foundations --skill troubleshooting-salesforcelabs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: troubleshooting
Source: https://github.com/SalesforceLabs/revenue-cloud-foundations/tree/main/.cursor/skills/troubleshooting
Command: npx skills add https://github.com/SalesforceLabs/revenue-cloud-foundations --skill troubleshooting-salesforcelabs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? When a Revenue Cloud Foundations build pipeline fails — a CCI flow step errors out, an SFDMU data load misbehaves, metadata deploy is blocked, or usage rating silently returns zero — this Skill maps the failing step to a known cause and a concrete fix, avoiding hours of blind debugging. ## Core Features & Use Cases - Step-to-section diagnosis: Maps the 34 steps of the prepare_rlm_org flow to categorized error sections covering permissions, decision tables, expression sets, SFDMU loads, billing, rating, DocGen, UX assembly, PRM, and constraints. - Silent-failure forensics: Explains ordering bugs where rated usage reads zero with no error, circular delete constraints in the usage graph, and polymorphic SOQL semi-joins that silently match nothing. - Live-org evidence capture: Provides SOQL queries against RevenueTransactionErrorLog, AsyncOperationTracker, and BatchJobPartFailedRecord to capture root causes before a data reset destroys them, plus a reference for the large-deal reprice/preprocess/activation pipeline. - Use Case: A CCI flow fails at step 18 with a PUR activation error. The Skill identifies duplicate Draft PURs as the cause and prescribes deleting rates before rating data, then reloading. ## Quick Start Ask the agent to diagnose why the prepare_rlm_org flow failed at a specific step using the troubleshooting skill.

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 Revenue Cloud build?▼

Identify the failing step number from the CCI output, then use the step-range table to jump to the matching error category such as SFDMU loading, metadata deploy, or rating. Run cci task run validate_setup first to rule out local toolchain issues.

Why does rated usage read zero with no error in Salesforce?▼

This silent failure is an ordering problem: usage was recorded after the period was orchestrated, the first orchestration pass closed past periods empty, or usage landed in the current period. Record usage into a past period before orchestrating, then run orchestration several times.

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

Duplicates on re-run mean the CSV is missing or has a mismatched $$ composite key column that must exactly match the externalId fields. Verify the header format like $$Field1$Field2 and run the dataset validation script to check all plans.

Can I use the same org alias for CCI and the Salesforce CLI?▼

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

Why can't I delete active billing records in Salesforce?▼

Active BillingTreatment and BillingTreatmentItem records can never be deleted due to a platform constraint. Only Draft records are deletable, so active records must be deactivated first if the platform allows, or the org must be recreated.

How do I find why an async rating or preprocess job failed?▼

Query BatchJobPartFailedRecord for per-record failures and AsyncOperationTracker for job outcomes, since batch failures do not surface in flow results. Capture this evidence before any account or data reset, which destroys it.