# Why transformers or vLLM says a model's architecture is not recognized, and how to fix it > Source: https://netray.co/troubleshoot/model-config-architecture-not-recognized > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: On-Prem AI Troubleshooting ## Short answer An unrecognized model type or architecture error means the checkpoint's config.json declares a model_type or architectures field that your installed version of transformers or vLLM has never heard of, because that model's implementation code was added in a later library release than the one you have installed. The fix is almost always to upgrade the serving library (transformers, vLLM, or both) to a version released on or after that model's launch, not to modify the checkpoint. ## Error Title Model type or architecture not recognized when loading a new model ## Error Signature ValueError: The checkpoint you are trying to load has model type `xyz` but Transformers does not recognize this architecture ## Alternate Signatures - KeyError: 'xyz' is not a valid model type, use one of ... - ValueError: Unrecognized configuration class ... for this kind of AutoModel - ValueError: Could not load model ... with any of the following classes ## Category model-loading ## Stack - transformers - huggingface - vllm ## Affects Newly released model architectures (new Llama, Qwen, DeepSeek, or Gemma generations) loaded with an older pinned transformers, vLLM, or accelerate version ## Quick Fix ### Fix it in a few minutes **Steps:** - Check the model's config.json for the model_type and architectures fields to identify exactly what is being requested. - Check your installed transformers version: python -c "import transformers; print(transformers.__version__)". - Check the model card or release notes for the minimum required transformers/vLLM version, usually stated at the top of the HuggingFace model page. - Upgrade the relevant library: pip install -U transformers (and accelerate, tokenizers) or upgrade vLLM to a version released after the model's announcement date. - If the model requires code not yet merged into a stable release, check whether the model card recommends installing from a specific git commit or using trust_remote_code with the repo's custom modeling file. - Retry loading after the upgrade; if it still fails, confirm no other pinned dependency (torch, tokenizers) is holding back a compatible sub-version. ## Symptoms - Error names the exact model_type string from config.json as unrecognized - The same code loads older or more established models (Llama 2, Mistral 7B) without any problem - The model was released very recently, often within days or weeks of the failure - pip show transformers reports a version older than the model's documented minimum requirement ## Causes ### Installed transformers (or vLLM) version predates support for this model architecture **Likelihood:** most-common **Explanation:** Every new model family that introduces architectural changes (new attention variant, new MoE routing, new positional encoding) needs corresponding Python modeling code added to transformers or to vLLM's model registry. If your environment pinned an older version before that code was merged and released, the AutoModel/AutoConfig classes simply have no entry for that model_type string and refuse to guess. **Fix:** Upgrade to a transformers or vLLM release published on or after the model's public release date. Check the model card for an explicit 'requires transformers >= X.Y' note, which model authors usually include for exactly this reason. **Commands:** - pip install -U transformers accelerate tokenizers - pip show transformers | grep Version ### Serving framework (vLLM, TGI, SGLang) has its own separate model registry that lags behind transformers support **Likelihood:** common **Explanation:** Inference servers implement their own optimized model definitions for performance (paged attention kernels, custom fused kernels) rather than reusing transformers' generic implementation directly. A model can be fully supported in transformers for text generation but still be unsupported in vLLM until the vLLM team adds a matching optimized implementation, producing the same class of error inside the serving stack instead of transformers itself. **Fix:** Check the serving framework's own supported-models list and changelog separately from transformers; upgrade vLLM/TGI/SGLang specifically, since a transformers upgrade alone does not add support inside a different inference engine. **Commands:** - pip install -U vllm - vllm --version ### Locked or vendored dependency pin in a Docker image or requirements.txt prevents the upgrade from actually taking effect **Likelihood:** occasional **Explanation:** A requirements.txt with transformers==4.x.0 pinned for reproducibility, or a Docker base image built months earlier, silently overrides an attempted pip install -U in a way that is easy to miss, especially inside multi-stage Docker builds where the final image copies a pre-built virtualenv from an earlier stage. **Fix:** Search all requirements files, Dockerfiles, and lockfiles for hard version pins on transformers, tokenizers, and vllm, and update them explicitly rather than relying on an ad hoc pip install in a running container. **Commands:** - grep -rn transformers requirements*.txt Dockerfile* ### Model genuinely requires trust_remote_code with custom modeling files that have not been merged into transformers at all **Likelihood:** occasional **Explanation:** Some model authors ship brand-new architectures purely as custom Python files in their HuggingFace repo (modeling_xyz.py) rather than waiting for upstream merge into transformers. In this case no version upgrade of transformers alone will resolve it; AutoModel needs trust_remote_code=True to load the repo's own Python implementation directly. **Fix:** Check the model card for explicit instructions to use trust_remote_code=True, and treat that code as executable third-party code requiring the same review process described in the trust_remote_code security page before running it in a regulated environment. **Commands:** - python -c "from transformers import AutoModelForCausalLM; AutoModelForCausalLM.from_pretrained('org/model', trust_remote_code=True)" ## Diagnostics ### Identify exactly what architecture is being requested **Command:** python -c "import json; c=json.load(open('config.json')); print(c.get('model_type'), c.get('architectures'))" **Interpretation:** This tells you precisely which model_type string and architecture class name the checkpoint expects, which you can then cross-reference against your installed library's supported list. ### Check installed library versions **Command:** pip show transformers vllm tokenizers accelerate | grep -E 'Name|Version' **Interpretation:** Compare these version numbers against the minimum requirement stated on the model card. An older date on any of these packages relative to the model's release date is the smoking gun. ### Search transformers' own registry for the model type **Command:** python -c "from transformers.models.auto.configuration_auto import CONFIG_MAPPING_NAMES; print('xyz' in CONFIG_MAPPING_NAMES)" **Interpretation:** False confirms your installed transformers build has no entry for this architecture at all, which is definitive proof an upgrade (or trust_remote_code) is required rather than a local config problem. ## Prevention Before adopting a brand-new model release in production, check its model card for the minimum transformers/vLLM version and add that as an explicit dependency floor, not just 'latest'. Track release notes for vLLM, SGLang, and transformers separately; supporting a new model in one does not imply support in the others. In air-gapped environments, plan your model-serving library upgrade cadence to arrive with (or ahead of) the model artifacts you intend to deploy, since you cannot pip install on demand once offline. Pin dependency versions deliberately and review them on a schedule, rather than freezing them accidentally via an old Docker base image. ## When To Escalate If your organization is standardized on an older, validated stack for compliance reasons and cannot casually upgrade transformers or vLLM, adopting a brand-new model architecture becomes a genuine platform upgrade project: validating the new library version, re-running your test suite, and re-certifying the environment, not a quick pip install. Treat it as a planned upgrade cycle. ## Faq ### Do I need to upgrade transformers and vLLM together? **Answer:** Not necessarily in lockstep, but both need to individually meet the new model's minimum version requirement for their respective code paths. Transformers support lets you load and run the model directly in Python; vLLM support is separately required if you serve it through vLLM's optimized engine. ### Is it safe to just use trust_remote_code instead of upgrading? **Answer:** It works technically, but it means running the model author's custom Python code directly rather than a vetted library implementation, and that code executes with full permissions in your process. Review it before running, and in regulated environments treat it the same as any third-party code you would vendor and audit. ### Why does the same model load fine with plain transformers but fail in vLLM? **Answer:** vLLM reimplements each supported architecture with custom, performance-optimized kernels rather than calling transformers directly, so its supported-model list lags behind transformers releases. Check vLLM's own documentation and changelog for that specific architecture's support status. ### How do I know the minimum version I need without trial and error? **Answer:** Check the model's HuggingFace model card, which model authors typically annotate with a required transformers version, and check the library's own release notes or changelog for the version that first mentions that model family by name. ## Search terms model type not recognized transformers, unrecognized configuration class, transformers does not recognize architecture, AutoModel unsupported model type, vllm model architecture not supported, upgrade transformers new model --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json