{"record":{"id":"097a54c1ad5bacfd","repo":"sgl-project/sglang","slug":"speculative-ngram-external-sam-budget-must-be-po","errorCode":null,"errorMessage":"--speculative-ngram-external-sam-budget must be positive when --speculative-ngram-external-corpus-path is set.","messagePattern":"--speculative-ngram-external-sam-budget must be positive when --speculative-ngram-external-corpus-path is set\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/speculative_hook.py","lineNumber":893,"sourceCode":"        declare_resolution(\n            server_args,\n            \"_handle_ngram\",\n            speculative_num_draft_tokens=12,\n        )\n        logger.warning(\n            \"speculative_num_draft_tokens is set to 12 by default for ngram speculative decoding. \"\n            \"You can override this by explicitly setting --speculative-num-draft-tokens.\"\n        )\n    if cfg.speculative_num_steps is None:\n        declare_resolution(\n            server_args,\n            \"_handle_ngram\",\n            speculative_num_steps=cfg.speculative_num_draft_tokens\n            // cfg.speculative_eagle_topk,\n        )\n    if cfg.speculative_ngram_external_corpus_path is not None:\n        if cfg.speculative_ngram_external_sam_budget <= 0:\n            raise ValueError(\n                \"--speculative-ngram-external-sam-budget must be positive when \"\n                \"--speculative-ngram-external-corpus-path is set.\"\n            )\n        if cfg.speculative_ngram_external_corpus_max_tokens <= 0:\n            raise ValueError(\n                \"--speculative-ngram-external-corpus-max-tokens must be positive when \"\n                \"--speculative-ngram-external-corpus-path is set.\"\n            )\n        if (\n            cfg.speculative_ngram_external_sam_budget\n            > cfg.speculative_num_draft_tokens - 1\n        ):\n            raise ValueError(\n                \"speculative_ngram_external_sam_budget must be less than or equal to \"\n                f\"speculative_num_draft_tokens - 1 ({cfg.speculative_num_draft_tokens - 1}).\"\n            )\n    logger.warning(\n        \"The mixed chunked prefill are disabled because of \"","sourceCodeStart":875,"sourceCodeEnd":911,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/speculative_hook.py#L875-L911","documentation":"When an external draft corpus is supplied via --speculative-ngram-external-corpus-path, SGLang builds a suffix-array model (SAM) over it for draft proposals. The SAM budget controls how many suffix-array matches are retained; a zero/negative budget makes the external corpus useless and indicates a misconfiguration, so the args hook requires it to be positive.","triggerScenarios":"Launching with --speculative-ngram-external-corpus-path set and --speculative-ngram-external-sam-budget <= 0 (default 0 when unset). Checked inside _handle_ngram after the corpus-path branch.","commonSituations":"Enabling the external corpus path but forgetting to set the SAM budget (it doesn't default to a positive value); copying configs from a version where the budget defaulted differently; passing 0 thinking it means 'auto'.","solutions":["Set --speculative-ngram-external-sam-budget to a positive value (also must be <= speculative_num_draft_tokens - 1)","Keep it within [1, speculative_num_draft_tokens - 1] to also satisfy the follow-up check","If you don't need the external corpus, remove --speculative-ngram-external-corpus-path"],"exampleFix":"# before\n--speculative-ngram-external-corpus-path /data/corpus.bin\n# after\n--speculative-ngram-external-corpus-path /data/corpus.bin --speculative-ngram-external-sam-budget 4","handlingStrategy":"validation","validationCode":"if server_args.speculative_ngram_external_corpus_path is not None:\n    assert server_args.speculative_ngram_external_sam_budget > 0\n    assert server_args.speculative_ngram_external_sam_budget <= server_args.speculative_num_draft_tokens - 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set the full external-corpus triple (path, sam-budget, max-tokens) together","Sanity-check 1 <= sam_budget <= num_draft_tokens - 1 in launch scripts"],"tags":["speculative-decoding","ngram","external-corpus","server-args","validation"],"backgroundTag":"invalid-launch-argument-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}