Troubleshooting (Preview)

This topic describes common Oracle Analytics Cloud MCP tools issues, their likely causes, and the recommended steps to resolve them.

Symptom	Likely Cause	Next Step
No catalog results	Wrong type, search term, permissions, or root folder ID.	Retry with search: "*", broader types, or no rootFolder.
describe_data fails for a table	Table name mismatch or unsupported table filter.	Call with tablesOnly: true, then use exact tableName.
Logical SQL column error	Column not fully qualified or not present in model.	Use describe_data and copy fullyQualifiedName.
Logical SQL returns too much data	Missing filters or row limit.	Add selective WHERE, deterministic ORDER BY, and FETCH FIRST.
XSA query fails	Incomplete XSA expression or missing table name in column references.	Use xsaExpr from search_catalog and full XSA(...)."Table"."Column" references.
ANSI aggregate looks wrong	A predefined measure’s default semantic aggregation might override AVG, MIN, or MAX.	If MIN, AVG, MAX, and SUM return the same value, don't rely on the requested statistic. Use Logical SQL for a true aggregation override, or retrieve lowest-grain rows and calculate the result outside Oracle Analytics Cloud.
Repeated identical grouped XSA rows	Grouped XSA results can repeat the same dimension and aggregate values.	Treat the result as suspect. Retry the query once with Logical SQL, using the exact XSA fullyQualifiedName expressions.
Workbook save validation error	Workbook JSON structure is invalid for OAC runtime.	Inspect validation metadata, fix structure, and retry once.
Export fails	Invalid workbook ID, canvas ID, render issue, or permissions.	Export all canvases first, then narrow to canvas IDs.
ACL update has unexpected effect	Wrong update mode or broad recursive target.	Prefer ReplaceMatchingAccounts; avoid recursive changes unless required.