afv-library/skills/platform-report-generate/references/errors-and-troubleshooting.md

Common Authoring Errors

Read this when a generated .report-meta.xml is rejected during deployment or fields don't appear in the report. Use these to validate the authored XML before handing it off; deployment itself is outside this skill's scope.

Error	Cause	Fix
Invalid report type 'X'	Report type doesn't exist or isn't deployed in the target org	Verify the report type API name. For custom report types, ensure <deployed>true</deployed> is set. Use platform-custom-report-type-generate skill to create if missing
Invalid field 'X' for report type 'Y'	Column name not recognized for the report type — used raw field API name instead of platform column name	Use platform column names (e.g. ACCOUNT_NAME not Account.Name). For custom fields, use ObjectApiName.FieldApiName__c. Use get_metadata_type_shape MCP tool to discover valid column names
Grouping field 'X' not found in columns	A <groupingsDown> or <groupingsAcross> field is not also listed as a <columns> entry	Add the grouping field as a <columns> block
Chart not valid for Tabular format	<chart> element present on a Tabular report	Remove the chart or change format to Summary or Matrix
Summary report requires at least one grouping	Format is Summary but no <groupingsDown> is defined	Add at least one <groupingsDown> block or change format to Tabular
Matrix report requires row and column groupings	Format is Matrix but <groupingsDown> or <groupingsAcross> is missing	Add both row and column groupings
Tabular report cannot have groupings	<groupingsDown> or <groupingsAcross> present on a Tabular report	Remove groupings or change format to Summary/Matrix
Invalid filter operation 'X'	Typo or unsupported operation value	Use a valid operation from filter-operations.md
Filter logic references filter N but only M filters exist	<filterLogic> references more filters than defined	Ensure filter numbers in the logic match the actual filter count
Report folder not found	Report file not inside a valid folder directory, or folder metadata file missing	Ensure the file is under <sourceDir>/reports/<FolderName>/ (check sfdx-project.json for source path) and a <FolderName>-meta.xml exists
Too many cross filters	More than 3 <crossFilters> elements	Reduce to 3 or fewer cross-filters
Joined report requires at least 2 blocks	<format> is Joined but fewer than 2 <block> elements	Add at least 2 block elements
Block format cannot be Tabular	A <block> inside a Joined report has <format>Tabular</format>	Change block format to Summary or Matrix
Aggregate types not valid for Tabular format	<aggregateTypes> specified on a column in a Tabular report	Remove aggregates or change format to Summary/Matrix
Invalid date interval 'X'	Typo in <interval> value inside <timeFrameFilter>	Use a valid interval constant (e.g. INTERVAL_CURRENT, INTERVAL_CURY)
Custom start/end date required for INTERVAL_CUSTOM	Interval is INTERVAL_CUSTOM but <startDate> or <endDate> is missing	Add both <startDate> and <endDate> in YYYY-MM-DD format

Common Pitfalls

Pitfall 1: Using API Field Names Instead of Platform Column Names

Wrong:

<columns>
    <field>Account.Name</field>  <!-- raw API name -->
</columns>

Right:

<columns>
    <field>ACCOUNT_NAME</field>  <!-- platform column name -->
</columns>

Standard fields have specific platform column names (e.g. OPPORTUNITY_NAME, STAGE_NAME, CLOSE_DATE). Custom fields use the format ObjectApiName.FieldApiName__c.

Pitfall 2: Forgetting Grouping Fields in Columns

Every field used in <groupingsDown> or <groupingsAcross> must also be present as a <columns> entry. Missing the column causes the grouping to fail.

Pitfall 3: Mismatched Format and Structure

If you want...	Use format	Must have
Flat list	Tabular	Only <columns>, NO groupings
Grouped rows	Summary	<columns> + <groupingsDown>
Cross-tab	Matrix	<columns> + <groupingsDown> + <groupingsAcross>
Multi-source	Joined	<block> elements (2-5), each with own columns/groupings

Pitfall 4: Chart Summary Column Syntax

The <summaryColumn> in a chart uses a special syntax for aggregate references:

• s!AMOUNT — Sum of Amount
• a!AMOUNT — Average of Amount
• m!AMOUNT — Max of Amount
• x!AMOUNT — Min of Amount
• RowCount — Record count

Pitfall 5: Joined Report Restrictions

• Joined reports do NOT support top-level <chart>, <columns>, or <groupingsDown> — everything goes inside <block> elements
• Each block must have its own <reportType> — blocks can use different report types
• Blocks align on common grouping fields for cross-block comparison
• Block format must be Summary or Matrix, never Tabular