Troubleshooting.
Every Trekport deployment failure routes through a classifier before it reaches a human. Each bucket carries a concrete resolution path. The four buckets below cover the failure modes you will see in production.
The four classifier buckets
| Bucket | Meaning | Resolution path | Workaround |
|---|---|---|---|
| Converter | The translation rule did not produce valid PostgreSQL. | Lands as a rule update in the next engine release. | Override the converted output for the affected object. The override survives subsequent runs. |
| Catalog | The extracted catalog is incomplete or misordered. | Lands as an extractor update in the next engine release. | Re-run the extractor against the affected schema with the version-aware flag, then resume the deployment. |
| Extension | PostgreSQL is missing an Oracle-equivalent function or package. | CREATE EXTENSION the missing component, or ship a customer-specific extension. | The deployer can retry the phase after the extension is installed. No manual rewrite needed. |
| Out of scope | The Oracle feature has no PostgreSQL equivalent. | Acknowledged gap. Engineering conversation if a long-term equivalent matters. | Accept the gap, adopt an application-level workaround, or scope it for the next release. |
Converter failures in detail
Converter failures mean the translation rule output did not compile on PostgreSQL. The deployment report lists the rule reference and the offending object so engineering can reproduce the case deterministically.
- The fix lands as a rule update in the next engine release.
- As a workaround, edit the file under
./converted/and re-deploy. The CLI honors an explicit override directory if you prefer to keep overrides out of the converted tree. - Recurring converter failures in the same area of the language are usually fixed by a single rule update — file one example, not many.
Catalog failures in detail
Catalog failures mean the deployer reached an object whose dependencies were not in the catalog mirror. The deployer reports the missing dependency, its referencing object, and the phase it was expected in.
- The most common case is an Oracle privilege that was filtered out of the extract. The fix is to re-run extraction with the relevant filter relaxed.
- A second common case is a private synonym in a schema that was excluded from extraction. The fix is to include the schema.
Extension failures in detail
Extension failures mean PostgreSQL is missing a function or package the converted output relies on. The report names the missing function and the extension that provides it.
- Most cases resolve with a
CREATE EXTENSIONon the target. The deployer retries the phase automatically once the extension is installed. - If the gap is enterprise-specific, the Trekport team ships a customer compatibility extension on the next release cycle. See the compatibility layer for the standard set.
Out-of-scope failures in detail
Out-of-scope failures mean PostgreSQL has no equivalent for the Oracle feature. Typical examples are FLASHBACK queries, the MODEL clause, certain ROWID-dependent patterns, and Oracle Spatial features not covered by PostGIS.
- The engine reports the affected object and the rationale.
- Acknowledge the gap, adopt an application-level workaround, or route the case through a Trekport engineering conversation for a long-term fix.
When to escalate
Escalate any of the following through the customer portal:
- A classifier output that is unclear.
- A failure that does not match one of the four buckets.
- A deployment report with an unexpected count in the converter bucket — a single new rule fix usually clears the whole class.
Trekport engineering triages portal escalations within five business days.