refactor(proxy): make the config file win over the database

[yuneng-berri]

TLDR

Problem this solves:

• Precedence varied per key: some DB-wins, some config-wins, some merged
• No way to tell which value is live without knowing the key
• A dashboard write to a config-declared key was stored, then ignored
• /config/field/info and /config/list disagreed inside one process

How it solves it:

• One rule: if the config file declares a key, the file owns it
• A key the file leaves out still comes from the database
• Writes to a config-owned key now 400 instead of being swallowed
• Both read endpoints resolve through the same store and report source

User Flow

Before: an admin edits a setting on the Admin UI settings page, the save succeeds, and nothing changes

1. Their config file has general_settings.max_parallel_requests: 111
2. They open http://localhost:4000/ui/?page=settings and change Max Parallel Requests to 999, then Save
3. The save returns 200 and the field shows 999
4. They send a burst of requests and the proxy still throttles at 111
5. They re-check: GET /config/field/info?field_name=max_parallel_requests says 999, GET /config/list?config_type=general_settings says 111, on the same running proxy
6. Nothing tells them the config file is the reason, so the only way out is to guess and remove the key from the file

After: the same save is refused up front and says exactly what to do

1. Their config file has general_settings.max_parallel_requests: 111
2. They open http://localhost:4000/ui/?page=settings, and Max Parallel Requests is shown as read-only with the value 111
3. If they call the API directly, POST /config/field/update with max_parallel_requests: 999 comes back 400: "general_settings key 'max_parallel_requests' is set in the config file and cannot be changed here", naming the file to edit
4. GET /config/field/info and GET /config/list both report 111 with "source": "config" and "editable": false
5. A setting the file leaves out, e.g. max_request_size_mb, still saves from the UI, comes back 200, and reads back with "source": "db" and "editable": true

Relevant issues

Affected release

Linear ticket

Resolves LIT-7803

Pre-Submission checklist

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Both runs use the same isolated Postgres and Redis and the same config file:

model_list:
  - model_name: qa-gpt
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: sk-1234
  store_model_in_db: true
  max_parallel_requests: 111
  maximum_spend_logs_retention_period: 30d

litellm_settings:
  drop_params: true

The LiteLLM_Config table is emptied before each run, so both start from the same state. Case 1 is a real call to OpenAI, billed.

Before (8fc9c46)

#### case 1: a chat completion still goes through
$ curl -s -X POST http://localhost:4000/v1/chat/completions -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"model":"qa-gpt","messages":[{"role":"user","content":"Reply with the single word: alive"}]}' | jq "{model, content: .choices[0].message.content, usage}"
{
  "model": "qa-gpt",
  "content": "Alive",
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 1,
    "total_tokens": 15
  }
}

#### case 2: editing a setting the config file declares (max_parallel_requests: 111)
$ curl -s -w "
HTTP %{http_code}
" -X POST http://localhost:4000/config/field/update -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"field_name":"max_parallel_requests","field_value":999,"config_type":"general_settings"}'
{"param_name":"general_settings","param_value":{"max_parallel_requests":999},"last_run_at":null,"reload_revision":0}
HTTP 200

#### case 3: reading back which value is live
$ curl -s "http://localhost:4000/config/field/info?field_name=max_parallel_requests" -H "Authorization: Bearer sk-1234"
{"field_name":"max_parallel_requests","field_value":999}
$ curl -s "http://localhost:4000/config/list?config_type=general_settings" -H "Authorization: Bearer sk-1234" | jq -c ".[] | select(.field_name==\"max_parallel_requests\")"
{"field_name": "max_parallel_requests", "field_type": "Integer", "field_description": "maximum parallel requests for each api key", "field_value": 111, "stored_in_db": true, "field_default_value": null, "premium_field": false, "nested_fields": null, "field_options": null, "field_tab": null}

#### case 4: editing a setting the config file leaves out (max_request_size_mb)
$ curl -s -w "
HTTP %{http_code}
" -X POST http://localhost:4000/config/field/update -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"field_name":"max_request_size_mb","field_value":42,"config_type":"general_settings"}'
{"param_name":"general_settings","param_value":{"max_request_size_mb":42,"max_parallel_requests":999},"last_run_at":null,"reload_revision":0}
HTTP 200
$ curl -s "http://localhost:4000/config/field/info?field_name=max_request_size_mb" -H "Authorization: Bearer sk-1234"
{"field_name":"max_request_size_mb","field_value":42}

After (0d9c515)

#### case 1: a chat completion still goes through
$ curl -s -X POST http://localhost:4000/v1/chat/completions -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"model":"qa-gpt","messages":[{"role":"user","content":"Reply with the single word: alive"}]}' | jq "{model, content: .choices[0].message.content, usage}"
{
  "model": "qa-gpt",
  "content": "alive",
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 1,
    "total_tokens": 15
  }
}

#### case 2: editing a setting the config file declares (max_parallel_requests: 111)
$ curl -s -w "
HTTP %{http_code}
" -X POST http://localhost:4000/config/field/update -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"field_name":"max_parallel_requests","field_value":999,"config_type":"general_settings"}'
{"detail":{"error":"general_settings key 'max_parallel_requests' is set in the config file and cannot be changed here","keys":["max_parallel_requests"],"section":"general_settings","resolution":"edit /private/tmp/precedence-qa/config.yaml to change it, or remove it from the file to let the database own it"}}
HTTP 400

#### case 3: reading back which value is live
$ curl -s "http://localhost:4000/config/field/info?field_name=max_parallel_requests" -H "Authorization: Bearer sk-1234"
{"field_name":"max_parallel_requests","field_value":111,"source":"config","editable":false}
$ curl -s "http://localhost:4000/config/list?config_type=general_settings" -H "Authorization: Bearer sk-1234" | jq -c ".[] | select(.field_name==\"max_parallel_requests\")"
{"field_name": "max_parallel_requests", "field_type": "Integer", "field_description": "maximum parallel requests for each api key", "field_value": 111, "stored_in_db": false, "field_default_value": null, "premium_field": false, "nested_fields": null, "field_options": null, "field_tab": null, "source": "config", "editable": false}

#### case 4: editing a setting the config file leaves out (max_request_size_mb)
$ curl -s -w "
HTTP %{http_code}
" -X POST http://localhost:4000/config/field/update -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"field_name":"max_request_size_mb","field_value":42,"config_type":"general_settings"}'
{"param_name":"general_settings","param_value":{"max_request_size_mb":42},"last_run_at":null,"reload_revision":0}
HTTP 200
$ curl -s "http://localhost:4000/config/field/info?field_name=max_request_size_mb" -H "Authorization: Bearer sk-1234"
{"field_name":"max_request_size_mb","field_value":42,"source":"db","editable":true}

Type

🧹 Refactoring

Caveats (if any)

Severe

• Breaking: a write to a config-declared setting now 400s
• Operators who edit those settings from the UI must remove them from the file
• A pass-through entry in the DB can no longer flip auth on a config-declared path

High

• Deleting a stored pass-through row used to leave the deleted route serving until restart; fixed here, but it is a live bug on main

Medium

• Deleting the last allowed IP locks everyone out, on main too: /delete/allowed_ip leaves allowed_ips: [], which denies every address, and the cleanup call is already locked out. Reproduced on the merge base, so not from this PR, but it makes the rest of test_config_misc_endpoints_e2e.py fail once that test runs
• The Admin UI still renders config-owned fields as editable until the dashboard PR lands
• Until then the user sees the 400 on save instead of a disabled input
• /config/field/info answers from the resolved settings now, not the stored row

Low

• source is exposed on both read endpoints so the dashboard can grey out fields
• The 786-case JSON fixture is gone; cases are generated from the rule table now

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_settings_store_precedence (0d9c515) with main (8fc9c46)}

[codecov]

Codecov Report

❌ Patch coverage is 97.13376% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/proxy_server.py	96.44%	6 Missing ⚠️
..._experimental/mcp_server/discoverable_endpoints.py	0.00%	1 Missing ⚠️
litellm/proxy/config_resolvers/settings_rules.py	97.77%	1 Missing ⚠️
litellm/proxy/config_resolvers/settings_store.py	98.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with both previous findings resolved and no new actionable issue established

Summary

This PR establishes config-file ownership for explicitly declared settings, falls back to database values for omitted keys, rejects conflicting control-plane writes, and reports configuration provenance through the read APIs. The latest changes also ensure deleted pass-through routes are unregistered and move prompt-injection heuristics off the event loop

• Introduces centralized settings precedence and provenance handling
• Rejects writes that conflict with config-owned values
• Aligns /config/field/info and /config/list
• Refreshes runtime side effects and route deletion behavior
• Adds focused unit and end-to-end coverage

_{Reviews (3) · Last reviewed commit: "test(e2e): assert config ownership inste..."}

[yuneng-berri]

@greptileai review

[yuneng-berri]

@greptile