{"record":{"id":"69a96b9b2cfb830a","repo":"sgl-project/sglang","slug":"speculative-ngram-external-corpus-max-tokens-mus","errorCode":null,"errorMessage":"--speculative-ngram-external-corpus-max-tokens must be positive when --speculative-ngram-external-corpus-path is set.","messagePattern":"--speculative-ngram-external-corpus-max-tokens 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":898,"sourceCode":"        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 \"\n        \"using ngram speculative decoding.\"\n    )\n\n    from sglang.srt.arg_groups.overrides import resolved_view\n","sourceCodeStart":880,"sourceCodeEnd":916,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/speculative_hook.py#L880-L916","documentation":"When using an external ngram draft corpus, --speculative-ngram-external-corpus-max-tokens bounds how many tokens of the corpus are indexed; a zero/negative max means nothing would be indexed. SGLang's args hook validates that this value is positive whenever the corpus path is set.","triggerScenarios":"Launching with --speculative-ngram-external-corpus-path set and --speculative-ngram-external-corpus-max-tokens <= 0 (explicitly or via a stale default).","commonSituations":"Setting only the corpus path and SAM budget but not max-tokens; porting a config from an older SGLang where the parameter did not exist or defaulted to unlimited; passing 0 expecting 'no limit'.","solutions":["Set --speculative-ngram-external-corpus-max-tokens to a positive token count covering your corpus","Size it >= the corpus token count if you want the whole corpus indexed","Drop the corpus path entirely if the external corpus isn't needed"],"exampleFix":"# before\n--speculative-ngram-external-corpus-path /data/corpus.bin --speculative-ngram-external-sam-budget 4\n# after\n--speculative-ngram-external-corpus-path /data/corpus.bin --speculative-ngram-external-sam-budget 4 --speculative-ngram-external-corpus-max-tokens 100000000","handlingStrategy":"validation","validationCode":"if server_args.speculative_ngram_external_corpus_path is not None:\n    assert server_args.speculative_ngram_external_corpus_max_tokens > 0","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set max-tokens to at least the corpus size when enabling an external corpus","Keep external-corpus flags in one config block so none are omitted"],"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"}