{"record":{"id":"c4ee420428f90f2b","repo":"run-llama/llama_index","slug":"llm-must-start-with-str-local-or-of-type-llm-or","errorCode":null,"errorMessage":"llm must start with str 'local' or of type LLM or BaseLanguageModel","messagePattern":"llm must start with str 'local' or of type LLM or BaseLanguageModel","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/llms/utils.py","lineNumber":78,"sourceCode":"                \"`llama-index-llms-openai` package not found, \"\n                \"please run `pip install llama-index-llms-openai`\"\n            )\n        except ValueError as e:\n            raise ValueError(\n                \"\\n******\\n\"\n                \"Could not load OpenAI model. \"\n                \"If you intended to use OpenAI, please check your OPENAI_API_KEY.\\n\"\n                \"Original error:\\n\"\n                f\"{e!s}\"\n                \"\\n******\"\n            )\n\n    if isinstance(llm, str):\n        splits = llm.split(\":\", 1)\n        is_local = splits[0]\n        model_path = splits[1] if len(splits) > 1 else None\n        if is_local != \"local\":\n            raise ValueError(\n                \"llm must start with str 'local' or of type LLM or BaseLanguageModel\"\n            )\n        try:\n            from llama_index.llms.llama_cpp.llama_utils import (\n                completion_to_prompt,\n                messages_to_prompt,\n            )  # pants: no-infer-dep\n\n            from llama_index.llms.llama_cpp import LlamaCPP  # pants: no-infer-dep\n\n            llm = LlamaCPP(\n                model_path=model_path,\n                messages_to_prompt=messages_to_prompt,\n                completion_to_prompt=completion_to_prompt,\n                model_kwargs={\"n_gpu_layers\": 1},\n            )\n        except ImportError:\n            raise ImportError(","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/llms/utils.py#L60-L96","documentation":"resolve_llm accepts either an LLM instance, a LangChain BaseLanguageModel, or a string — but strings are only valid in the form 'local[:<model_path>]' which triggers LlamaCPP loading. Any other string (a bare model name like 'gpt-4', a path, an arbitrary label) fails this check with a ValueError.","triggerScenarios":"Passing Settings.llm = 'gpt-4o' or llm='some-model-name' to a constructor that resolves LLMs; passing a filesystem path string that doesn't start with 'local:'.","commonSituations":"Assuming the string is a model identifier (a common expectation from other SDKs); migrating configs where llm was previously an object and got serialized to a string.","solutions":["To use OpenAI: from llama_index.llms.openai import OpenAI; Settings.llm = OpenAI(model='gpt-4o').","To use a local GGUF model: pass 'local:/path/to/model.gguf' (and install llama-index-llms-llama-cpp).","Pass an actual LLM/LangChainLLM instance instead of a string."],"exampleFix":"# before\nSettings.llm = \"gpt-4o\"  # ValueError\n# after\nfrom llama_index.llms.openai import OpenAI\nSettings.llm = OpenAI(model=\"gpt-4o\")\n# local model path\nSettings.llm = \"local:/models/llama-2-7b.gguf\"","handlingStrategy":"type-guard","validationCode":"from llama_index.core.llms import LLM\nfrom llama_index.core.llms.utils import BaseLanguageModel\n\ndef is_acceptable_llm_value(llm) -> bool:\n    if isinstance(llm, LLM):\n        return True\n    if BaseLanguageModel is not None and isinstance(llm, BaseLanguageModel):\n        return True\n    return isinstance(llm, str) and llm.split(\":\", 1)[0] == \"local\"","typeGuard":"def is_local_llm_spec(value) -> bool:\n    return isinstance(value, str) and value.split(\":\", 1)[0] == \"local\"","tryCatchPattern":"try:\n    resolved = resolve_llm(llm_value)\nexcept ValueError as e:\n    if \"must start with str 'local'\" in str(e):\n        raise ValueError(\"Pass an LLM instance or 'local:<model_path>', not a model name\") from e\n    raise","preventionTips":["Never pass bare model-name strings as the llm value.","Construct provider LLM objects (OpenAI(...), etc.) for hosted models.","Use the 'local:<path>' form only for llama.cpp GGUF models."],"tags":["llama-index","configuration","llm-resolution","validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}