Troubleshooting
Common messages and what to do about them.
Start with:
bsm 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 bsm rework; for a harmless edit such as a revert fix, use bsm 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.
“… cannot run inside a transaction”
Lint BSM001. 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 bsm 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 bsm. bsm diff-schema lists what changed since the last deploy; then either undo it or capture it as a new change. See Schema drift.
BSM004: “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 bsm 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. bsm 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; bsm never rewrites CMK metadata.
macOS: “bsm cannot be opened”
Run xattr -d com.apple.quarantine bsm once, or install the .NET tool.
Support
Email support@lonebadger.tech or open an issue on GitHub. Include bsm --version, the command, and the output of bsm doctor. Never send passwords or tokens.