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.