Platform Gotchas Quick Reference
A quick-lookup table of Microsoft Fabric platform quirks, organized by category. Each row links to the Troubleshooting page for detailed symptom-cause-fix writeups.
SQL & Data
| Gotcha | Impact | Fix |
|---|---|---|
| Case-sensitive quoted identifiers | Queries fail in Fabric that work locally in DuckDB | Use bracket notation [Column] or normalizing CTE |
datetime2 requires explicit precision | Error 24597 on table creation | Always use datetime2(6) |
| Entire transaction rolls back on ANY error | Partial success disappears — all changes lost | Use autocommit=True in pyodbc for mixed DDL scripts |
| Error 15151 is ambiguous | Same error for missing schema AND missing object | Check for "15151", not "42S02"; verify both schema and object exist |
Bare varchar defaults to varchar(30) | Silent data truncation, fewer rows after GROUP BY | Always specify explicit length: varchar(500) |
| dbt contract exact match | Build fails on column name case or character mismatch | Ensure SELECT aliases match contract name: fields exactly |
Git Sync
| Gotcha | Impact | Fix |
|---|---|---|
| PreferRemote removes ALL non-git items | Warehouses and other items are deleted from workspace | Only use PreferRemote on empty workspaces |
| Git sync always imports regardless of strategy | Unexpected workspace changes after sync | Strategy only controls conflict resolution, not import behavior |
| Disconnect doesn't remove synced items | Old items remain after disconnecting git | Explicitly delete items before reconnecting |
| Report GUIDs are environment-specific | PowerBIEntityNotFound when deploying to new env | Use fabric-cicd parameter files for GUID substitution |
| Lakehouse needs 3 files | MissingItemDefinitionFiles error | Commit .platform, lakehouse.metadata.json, shortcuts.metadata.json |
| No auto-refresh after push | Workspace content stays stale | Trigger sync via REST API or portal manually |
Auth & SPNs
| Gotcha | Impact | Fix |
|---|---|---|
REST API /git/connect rejects SPNs | PrincipalTypeNotSupported error | Use Terraform fabric_workspace_git resource instead |
| ODBC SPN auth times out in CI | dbt builds hang then fail on Ubuntu agents | Use CLI auth (az account get-access-token) |
| Creating SPN gets auto-Admin | PrincipalAlreadyHasWorkspaceRolePermissions | Skip explicit Admin assignment for creating SPN |
| Object ID vs Client ID confusion | Auth or RBAC fails depending on which GUID is used | Object ID for role assignments, Client ID for token acquisition |
| MI needs Fabric tenant setting | 403 despite correct workspace roles | Add MI to security group in Fabric Admin Portal; wait 1 hour |
| MI needs Viewer on Gold for queries | Export queries fail with permission error | Assign Viewer via Terraform fabric_workspace_role_assignment |
| Wrong token scope causes 401 | Fabric API calls fail with valid credentials | Use api.fabric.microsoft.com/.default for REST, database.windows.net/.default for TDS |
| Fabric Admin API needs Capacity Admin | CU monitoring returns 403 | Grant Capacity Admin in Fabric admin portal (not ARM RBAC) |
TMDL & Semantic Models
| Gotcha | Impact | Fix |
|---|---|---|
description: causes parse failure | Workload_FailedToParseFile | Use /// triple-slash syntax, not description: key-value |
| DAX reserved words cause opaque errors | SYNTAXERROR with no useful message | Quote table names with single quotes: 'refresh'[column] |
| DirectLake table with only measures fails | Semantic model won't load | Include at least one column (e.g., hidden dummy column) |
sourceColumn must match dbt output exactly | Model deployment fails or shows wrong data | Use exact snake_case names from dbt output |
| No calculated columns in DirectLake | Design limitation | Compute all values in dbt, not in the semantic model |
Reports
| Gotcha | Impact | Fix |
|---|---|---|
| Embedded GUIDs are environment-specific | Reports fail in UAT/PROD | Use parameter-ENV.yml for GUID substitution |
pbiModelDatabaseName in .pbir | Workload_FailedToParseFile | Remove field; use only connectionString with semanticmodelid |
Azure Functions
| Gotcha | Impact | Fix |
|---|---|---|
No az CLI on Linux Consumption | Timer functions crash with file-not-found | Use DefaultAzureCredential from azure.identity |
requests table empty in App Insights | Cannot monitor function invocations | Change host.json "Host.Results" to "Information"; use traces table |
| Cold-start telemetry loss | Function ran but no telemetry appears | Check timer status blobs in Storage Account |
| past_due cascading | Rapid repeated runs, host restarts | Ensure execution time is well within schedule interval |
Workspace & Infrastructure
| Gotcha | Impact | Fix |
|---|---|---|
| Case-sensitive git connection names | Terraform git connection fails silently | Use exact case: geris-devops, insights-requests |
| Branch policies block Fabric UI commits | Cannot save changes from Fabric portal | Use unprotected feature branches for UI development |
| Never mix Terraform + git sync in one workspace | State conflicts, data loss | Separate Gold (Terraform) from Bronze/Semantic/Reports (git sync) |
.platform logicalId is environment-specific | Cross-env sync fails | Each environment gets its own logicalId; git sync assigns on first creation |
Related Pages
- Troubleshooting — detailed narrative for each gotcha
- Emergency Procedures — recovery procedures when gotchas bite
- ADR Decision Log — decisions that prevent some gotchas