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.
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.