{"record":{"id":"44abe4a1f9d00c76","repo":"sgl-project/sglang","slug":"dflash-mask-token-must-be-a-non-empty-string-got","errorCode":null,"errorMessage":"DFLASH mask_token must be a non-empty string, got {mask_token!r}.","messagePattern":"DFLASH mask_token must be a non-empty string, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/speculative/dflash_worker_v2.py","lineNumber":876,"sourceCode":"            )\n\n            assert self._draft_block_end_buf is not None\n            block_end = self._draft_block_end_buf[:bs]\n            torch.add(draft_prefix_lens, block_size, out=block_end)\n            assign_req_to_token_pool_func(\n                req_pool_indices,\n                self.draft_model_runner.req_to_token_pool.req_to_token,\n                draft_prefix_lens,\n                block_end,\n                verify_out_cache_loc_2d.reshape(-1),\n                bs,\n            )\n\n    def _resolve_mask_token_id(\n        self, *, mask_token: str, mask_token_id: Optional[int] = None\n    ) -> int:\n        if not isinstance(mask_token, str) or not mask_token:\n            raise ValueError(\n                f\"DFLASH mask_token must be a non-empty string, got {mask_token!r}.\"\n            )\n\n        vocab_size = int(self.target_worker.model_runner.model_config.vocab_size)\n        if mask_token_id is not None:\n            resolved_id = int(mask_token_id)\n            if resolved_id >= vocab_size:\n                raise ValueError(\n                    \"DFLASH mask_token_id is outside the target vocab size. \"\n                    f\"mask_token_id={resolved_id}, vocab_size={vocab_size}. \"\n                    f\"This likely means mask_token={mask_token!r} requires vocab expansion beyond the model's embedding size. \"\n                    \"SGLang does not support resizing target embeddings for DFLASH yet.\"\n                )\n\n            tokenizer = getattr(self.target_worker, \"tokenizer\", None)\n            if tokenizer is not None:\n                token_id_from_vocab = tokenizer.get_vocab().get(mask_token, None)\n                if (","sourceCodeStart":858,"sourceCodeEnd":894,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/speculative/dflash_worker_v2.py#L858-L894","documentation":"Thrown during DFLASH worker initialization when the configured mask_token is not a non-empty string. DFLASH drafts rely on a mask token to represent masked positions; the worker validates it before resolving its token id against the target vocab. Passing None, an int, or '' fails here with the offending value echoed.","triggerScenarios":"Server/speculative config where speculative_dflash_mask_token is omitted from the config class default and ends up None, set to an integer id by mistake, or set to the empty string in a launch script/JSON config.","commonSituations":"Hand-written launch scripts or overrides that set the mask token to an id (e.g. 128000) instead of the string form; config migration dropping the field; YAML/JSON quoting mistakes producing non-string values.","solutions":["Set the mask token as its string form, e.g. --speculative-dflash-mask-token \"<mask>\" (or the model's documented mask token string)","If you only know the id, find the token string via tokenizer.decode([id]) and pass that string","Remove empty-string overrides so the model's default mask token applies"],"exampleFix":"# before\n--speculative-algorithm DFLASH \\\n--speculative-dflash-mask-token \"\"\n\n# after\n--speculative-algorithm DFLASH \\\n--speculative-dflash-mask-token \"<|mask|>\"","handlingStrategy":"validation","validationCode":"mask_token = server_args.speculative_dflash_mask_token\nassert isinstance(mask_token, str) and mask_token, (\n    f\"mask_token must be a non-empty string, got {mask_token!r}\"\n)","typeGuard":"def is_valid_mask_token(v) -> bool:\n    return isinstance(v, str) and len(v) > 0","tryCatchPattern":null,"preventionTips":["Pass the mask token as its string form, never its integer id","Quote token strings in JSON/YAML launch configs","Omit the flag to use the model's documented default"],"tags":["sglang","speculative-decoding","dflash","config-validation","tokenizer"],"backgroundTag":"invalid-config-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}