Skip to content

fix(serve): refuse a bad LAYA_LOG_LEVEL with a message, not a traceback - #1227

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-log-level-refusal
Oct 15, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-log-level-refusal

Conversation

@aashish254

Copy link
Copy Markdown
Contributor

What

laya-serve now resolves LAYA_LOG_LEVEL in laya/serve.py instead of handing the raw environment
value to uvicorn. A new _resolve_log_level() sits next to _resolve_port(), strips and lowercases
the value, treats blank as unset, and refuses a name uvicorn does not know with a SystemExit that
lists the accepted spellings. main()'s log_level= argument calls it.

The accepted names are read from uvicorn.config.LOG_LEVELS at the moment of validation, so the
refusal cannot list a set uvicorn itself disagrees with.

Why

main() did log_level=os.environ.get("LAYA_LOG_LEVEL", "info") and uvicorn looks that value up
with LOG_LEVELS[self.log_level.lower()] — it lowercases, and nothing strips or validates. So every
one of these aborted the CLI with a bare KeyError raised inside Config.configure_logging, after
the app is built:

LAYA_LOG_LEVEL=verbose    -> KeyError: 'verbose'
LAYA_LOG_LEVEL=""         -> KeyError: ''
LAYA_LOG_LEVEL="  "       -> KeyError: '  '
LAYA_LOG_LEVEL=" INFO "   -> KeyError: 'info '

Three things are wrong with that surface. It is a traceback, and the variable's own neighbour in the
same file states the opposite policy — _resolve_port's docstring is "Exits with a message instead
of a traceback"
, and this is the only other raw env read on that uvicorn.run call. The exception
names neither the variable nor the caller, and it prints the lowercased value, so ' INFO '
reports KeyError: 'info ', which looks like a uvicorn bug rather than a padded value in a .env.
And the blank case is the family's: LAYA_LOG_LEVEL= is what a declared-but-unfilled line in a
.env, a Compose file, or a CI matrix writes, and nine of the eleven LAYA_* readers already answer
that with the documented default.

This also brings LAYA_LOG_LEVEL under the same audit as the rest of the table: naming the default
DEFAULT_LOG_LEVEL at the read is the shape tests/test_env_docs.py derives a documented default
from, so a future change to it has to move docs/http-api.md's row in the same PR (mutant M7 below
is exactly that edit, and it turns the audit red).

How it was verified

Three new tests in tests/test_serve.py:

  • test_resolve_log_level_refuses_a_bad_value_by_name — unset and the three blank spellings answer
    DEFAULT_LOG_LEVEL; each of uvicorn's own six names still works when written upper case and
    padded; six bad spellings (verbose, INFOO, notset, none, 0, warn) raise SystemExit
    with the message compared in full, so the listed set is checked against LOG_LEVELS rather than
    against a copy.
  • test_a_bad_log_level_is_refused_before_uvicorn_sees_it — drives main() with uvicorn.run
    captured, the same seam test_accepted_connections_set_tcp_nodelay uses: " WARNING " arrives
    as "warning", "" arrives as the default, and verbose raises before uvicorn.run is reached
    (captured == {}).
  • test_uvicorn_dies_on_the_values_the_resolver_refuses — the harm witness, written against uvicorn
    with no laya code on the path, pinning that the five spellings really do raise KeyError and
    that info / warning / INFO construct fine. This is what laya-serve printed before.

The real CLI, run as python -m laya.serve with LAYA_PRELOAD=0 HF_HUB_OFFLINE=1 in a worktree at
origin/main (432312b) and in this branch, PYTHONPATH=. in both:

LAYA_LOG_LEVEL before after
verbose exit 1, KeyError: 'verbose' exit 1, invalid LAYA_LOG_LEVEL 'verbose': must be one of critical, debug, error, info, trace, warning
"" exit 1, KeyError: '' serves, INFO: Uvicorn running on http://0.0.0.0:8123
" " exit 1, KeyError: ' ' serves, same INFO line
info serves serves
" WARNING " exit 1, KeyError: ' warning ' serves, and prints no startup line — the INFO banner is below warning, so the padded value reached uvicorn as warning rather than falling back
python -m pytest tests/test_serve.py -q                 # 298 passed, 1 skipped (same file on main: 295 passed, 1 skipped)
python -m pytest tests/test_serve.py -q -k "log_level or uvicorn_dies or LAYA_LOG"   # 3 passed
python tests/test_env_docs.py                           # exit 0, 63 passed, 0 failed
python tests/test_packaging.py                          # 170 passed, 0 failed
python tests/test_compose_env.py                        # 304 passed, 0 failed
python -m pytest tests/test_mcp_device.py -q            # 51 passed
ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120    # All checks passed!
python -m compileall -q laya/ tests/                    # exit 0

No line in the diff exceeds 120 characters. Diff is 2 files, +105/-1, scanned for secrets: no match
for api[_-]?key|secret|passw|credential|BEGIN .*PRIVATE|ghp_|xox[baprs]-|sk-[A-Za-z0-9]{10,}|AKIA|hf_[A-Za-z0-9]{20,}.

Mutation check, each mutant applied to laya/serve.py, the three new tests plus the whole file run,
then git checkout -- laya/serve.py:

mutant result
blank is not special-cased KILL (2 failed)
the accepted-name check is skipped KILL (2 failed)
the value is lowercased but not stripped KILL (2 failed)
the caller's case is returned instead of normalised KILL (2 failed)
the listed set drops trace KILL (1 failed)
main() reads the environment directly again KILL (1 failed)
DEFAULT_LOG_LEVEL changed to a value the table does not say KILL — test_env_docs.py fails defaults/docs/http-api.md's LAYA_LOG_LEVEL cell says what the code does

git diff --quiet after the harness: clean, every file restored.

Docs are unchanged on purpose: docs/http-api.md:42 and docs/docker.md:347 describe the value as
"uvicorn log level", which is still exactly true — the accepted set is uvicorn's, not a new one — and
the documented default info is what the code answers. Hunk-wise the branch is clear of the three
open PRs that touch these files (#667, #687, #716): laya/serve.py is touched at 738-770 and 1564,
tests/test_serve.py at 27, 36 and 1645, and none of those three PRs has a hunk in those ranges.

Checklist

  • Focused on one change (split unrelated work into another PR)
  • Rebased on the latest main (branched from 432312b; git merge-base HEAD origin/main is 432312b)
  • Tests pass locally (tests/test_serve.py 298 passed / 1 skipped, plus the suites listed above)
  • Docs or examples updated when the public API changed — no public API change; the accepted values
    and the default are what the pages already say

laya-serve passed LAYA_LOG_LEVEL straight to uvicorn, which indexes its own
LOG_LEVELS with .lower() and no .strip(), so a typo, a padded value from a .env,
and a blank LAYA_LOG_LEVEL= all aborted with a bare KeyError naming the
lowercased value instead of the variable. Resolve it in serve.py the way
_resolve_port already resolves LAYA_PORT, against uvicorn's own LOG_LEVELS so the
refusal cannot list a set uvicorn disagrees with, and read blank as unset like the
rest of the LAYA_* family.
@NandhaKishorM
NandhaKishorM merged commit f60c656 into NandhaKishorM:main Oct 15, 2026
44 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged in 0.4.8.

Reading the accepted names out of uvicorn's own LOG_LEVELS rather than restating a list is what makes this maintainable: the two cannot drift, and the message names whatever uvicorn actually accepts.

The diagnosis is precise. uvicorn lowercases but does not strip, so a value copied out of a .env with padding dies in Config.configure_logging with a bare KeyError that reads as a uvicorn bug, from the one variable whose siblings in this file promise a message. Importing LOG_LEVELS inside the function keeps laya.serve importable without uvicorn, which the module's other lazy imports already rely on.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants