Troubleshooting
Common messages and what to do about them.
Start with:
trek doctor -e <environment> -v
It checks configuration, Entra sign-in, the connection, server facts, the journal and environment resources, and reports each separately.
“These changes were edited after they were deployed”
A deployed change's scripts changed (even whitespace). For new behaviour, restore the deployed version and use trek rework; for a harmless edit such as a revert fix, use trek repair. See Fixing deployed changes.
“This database belongs to environment 'test'…”
You are pointing one environment's settings at another environment's database. Check --env and the host/database. If the database was copied on purpose, pass --claim-environment once.
“Timed out … waiting for the deploy lock”
Another deploy is running against the database. Wait, or raise lockTimeoutSeconds.
“This database has a Badger SQL Migrate journal …” or “… but bsm.yaml is there”
The project or database comes from Badger SQL Migrate, trek's earlier name. Rename the project files and move the journal once, as the message shows; see Upgrading from Badger SQL Migrate.
“… cannot run inside a transaction”
Lint TREK001. Mark the change !notx in the plan and make the script re-runnable.
“unknown variable {x}”
Define it under variables:, pass --var x=…, write {{x}} for a literal, or set preprocessor.unknown: keep.
“renders differently than when it was deployed”
A variable used by the change changed value. Run trek vars; restore the value, or use --allow-variable-drift if the change is intended.
“Changes … come before changes already deployed” (strict ordering)
A change merged above changes already in this database. In dev, use --ordering dependency or rebase; production should never see this if it only receives released plans.
“schema drift”
Something changed the schema outside trek. trek diff-schema lists what changed since the last deploy; then either undo it or capture it as a new change. See Schema drift.
TREK004: “SYSTEM_VERSIONING is turned OFF … and not turned back ON”
The script switches versioning off (usually to change the table) but never back on. Add ALTER TABLE … SET (SYSTEM_VERSIONING = ON (HISTORY_TABLE = …)) at the end, or drop the table if that is the intent. See Temporal tables and partitions.
“Bundle … failed verification”
A file in the bundle was changed, added or removed after it was built. Rebuild it from source control with trek bundle create; never edit a bundle.
Entra: “credential unavailable” or browser does not open
On SSH or headless machines use entraDeviceCode. For CLI credentials, sign in with az login first. trek auth clear resets saved sign-ins.
Linux: token cache error
Install libsecret (and a keyring), use entra.tokenCache: memory, or set allowUnencryptedTokenCache: true.
Kerberos on macOS/Linux fails
Run kinit user@REALM, check klist, and set connectionProperties: { Server SPN: MSSQLSvc/host:1433 } if the SPN differs.
“column master key … cannot be changed”
The database's CMK points to a different key path. Add a new CMK name and rotate; trek never rewrites CMK metadata.
macOS: “trek cannot be opened”
Run xattr -d com.apple.quarantine trek once, or install the .NET tool.
Support
Email support@lonebadger.tech or open an issue on GitHub. Include trek --version, the command, and the output of trek doctor. Never send passwords or tokens.