Understanding undetermined
Every SQLens result is one of four values: pass, fail, undetermined, or
not_applicable. The first two are familiar. The third is the one that makes the tool
trustworthy, and it is worth a page of its own — the fourth exists so that the third
keeps meaning what it says.
That is a single finding. The run as a whole has three, and the difference is not a
discrepancy: summary.overall_status in Contracts is pass, fail or
undetermined, and it can never be not_applicable — a run where every check declined to
apply reports pass, because nothing failed and nothing was left unlooked-at. Reading the
four-value vocabulary onto the envelope field is the mistake this note exists to prevent.
The model
A check that cannot run is never reported as a pass. If SQLens could not obtain a
migration's SQL, could not reach the server, or could not determine the server
version, it says so — as an undetermined result with a named reason — instead of
staying quiet and letting the run look clean. A green run that never actually
checked something is the most expensive kind of false confidence there is, so
SQLens does not produce one. A skip without a reason is a bug, not a feature.
An undetermined is not a failure and it is not your mistake. It means SQLens was
honest about a limit rather than guessing past it.
not_applicable — the check that had nothing to run against
An undetermined check wanted to run and could not. A not_applicable check had
nothing to look at in the first place: MySQL has no row-level security and no
pg_hba.conf, so the rules that judge those have no subject on that engine. A managed
provider that terminates TLS at its own proxy makes the server's ssl setting say
nothing about whether your connections are encrypted.
Those used to be reported as silence, and silence is the problem. A reader who sees no row-level-security finding concludes that tenant separation was examined and found in order. It was not examined at all.
The distinction is not bookkeeping. It decides your exit code:
--strict escalates it | In the baseline | In the summary | |
|---|---|---|---|
undetermined | yes — a question you left open can stop a deploy | no | its own count |
not_ | no | no | its own count, beside undetermined |
Escalating a not_applicable would put a line in your pipeline that no change of yours
can ever remove: your MySQL server is not going to grow row-level security. So
--strict leaves it alone, and the summary counts it separately, so "7 undetermined"
never quietly includes checks that were never applicable.
There is nothing to do about a not_applicable. It is there so you know what was not
looked at, and so that its absence from the report cannot be read as a pass.
0 fail and exit code 3 at once
A deploy can stop on a run whose summary says that nothing failed:
summary: 0 fail, 1 undetermined (missing_privilege: 1), 0 suppressed
and the step still ends with exit code 3. Both are true. fail counts the checks that
looked and found a problem. An undetermined check could not look, so it is never counted
there: a run whose only open question was the privilege table would otherwise claim it had
found something wrong with your privileges. The exit code carries the other half.
sqlens:predeploy is fail-closed, so a question it could not answer holds the deploy, and the
other commands do the same under strict_undetermined.
So read the exit code, not the count. The reasons in brackets say what could not be answered,
and sqlens:predeploy writes each such check with its reason after the report, on STDERR.
The pre-scan is deliberately conservative
Most undetermined results in the lint suite come from the static pre-scan, which
reads a migration before it is captured and flags anything pretend mode cannot see
truthfully — a side effect it would fire, a query result it depends on, an
introspection guard, a call into your own code, a call it cannot resolve at all
(CAP.PRESCAN.DYNAMIC_CALL). The pre-scan is deliberately
conservative: it would rather flag a migration you know is fine than let one slip
through that quietly does something pretend could not observe. A flag is not an
accusation. It is SQLens saying "I cannot be sure about this one in pretend mode",
and the reasons below are how you make it sure.
A stated honesty limit. The pre-scan is syntactic pattern recognition, not
taint or data-flow analysis. It sees one level: it recognizes a call, but it does
not follow the call into the code it reaches. That is most visible in
CAP.PRESCAN.INDIRECT_CALL, which flags a
migration that reaches its effect through your own code — (new Backfill)->run() —
without knowing what run() does. It flags conservatively because the alternative
is a silent pass exactly where a real side effect could hide. When you know a class
is safe, the allowlist is the intended way to say so. That check is preview, and a
run that does not admit the tier executes such a call in pretend mode without it; the
rule's page says how to turn it on.
The capture is the second net. A guard the pre-scan did not recognize still sends
its question to the database, and a pretend capture that holds a read of the system
catalog is reported by
CAP.L0.UNDETERMINED_CAPTURE with the reason
pretend_limit, at the statement that read it, rather than judged as if it were whole.
Capture modes says which reads count.
The four ways to resolve one
- Run it in shadow mode. Shadow mode executes the migration for real against a
disposable database, so the empty-result and guarded-block limits of pretend mode
disappear. This is the truth mode, and it is what most
undeterminedreasons point you to. See Capture modes. - Change the migration so pretend can capture it. Often the cleaner fix: move a data backfill out of the migration and into a job the deploy dispatches, or drop an introspection guard that is not actually needed. The migration then captures whole in pretend mode.
- Suppress it deliberately. If you have decided a flagged migration is fine — a helper you know is harmless, a pattern you accept — record that decision as a suppression. A suppression is a documented choice, and it is always shown as such in the report, so it never looks like an ordinary clean result.
- Let one deploy proceed past it.
sqlens:predeploy --allow-undeterminedis the coarse way out. It lets that run proceed past every check that could not answer, not past a chosen one, and only a real finding still blocks. It belongs on the command line of a run you are watching, not in a deploy script that runs it every time: there it turns a fail-closed gate into one that never stops for a question it cannot answer, including whether the deploy may do what it is about to do. Making the check answerable keeps the gate, and most predeploy questions become answerable once its role can read what they ask about, see Predeploy permissions. When a project can name what it deploys without, the list of reasons insqlens.deploy.predeploy.allow_undeterminedis the narrower form.
The one thing you should never do is treat an undetermined as a pass by ignoring
it. It is the tool telling you where it could not see; the reasons above are how you
give it sight.