Why transformers blocks loading with a trust_remote_code error, and what to actually do about it
ValueError: Loading this model requires you to execute the configuration file in that repo on your local machine. You can inspect the repository content at ... You can inspect the repository content at ... and set the option `trust_remote_code=True` to remove this error.
Also appears as
- ValueError: The repository for org/model contains custom code which must be executed to correctly load the model
- This model requires you to execute custom code
Short answer
This error is transformers deliberately refusing to run arbitrary Python code from a model repository without explicit consent, because loading such a model means executing the repository author's custom modeling_*.py file directly in your process with full permissions, not just deserializing tensor data. Passing trust_remote_code=True removes the error but does not remove the risk; in a regulated or air-gapped environment the correct approach is to review that code yourself, vendor a pinned copy of it, and only then load with trust_remote_code=True against your reviewed copy.
Affects: Models shipped with custom Python modeling code in their HuggingFace repo rather than upstream transformers support, any transformers version with this safety check
Fastest safe path
- 1Do not immediately set trust_remote_code=True and move on; first open the repo's Python files (usually modeling_*.py, configuration_*.py) on huggingface.co and read them.
- 2Check specifically for network calls, subprocess/os.system usage, file writes outside expected paths, or obfuscated code, which are the real risks this flag exposes you to.
- 3Pin an exact commit/revision when you do load it, so the code cannot silently change to something you have not reviewed on a later run.
- 4For a one-off trusted evaluation, load with trust_remote_code=True and revision="<commit-hash>" explicitly.
- 5For production or regulated environments, copy the reviewed code into your own internal repo, remove the trust_remote_code dependency entirely by loading your vendored copy, and track it under your own change control.
How to confirm this is your problem
- Error appears specifically for certain model repos (often very new architectures, research releases, or vendor-specific models) but not for standard transformers-native models
- The model card explicitly mentions custom code or 'requires trust_remote_code=True' in its usage instructions
- Error blocks loading entirely with no partial success, since transformers refuses before executing any of the custom code
Root causes and fixes
Model architecture is implemented as custom Python files in the repo rather than merged into upstream transformers
transformers' AutoModel classes normally load from a fixed, audited set of architecture implementations shipped with the library itself. When a model author ships their own modeling_xyz.py alongside the weights (common for brand-new or research architectures released before upstream integration), transformers has no built-in implementation to use and must dynamically import and execute that repo's Python file instead, which is fundamentally different from loading safetensors weight data.
Fix: This is by design, not a bug to fix; the decision is whether to trust and load that specific code. Review it, then pass trust_remote_code=True with a pinned revision if you accept the risk.
python -c "from transformers import AutoModelForCausalLM; AutoModelForCausalLM.from_pretrained('org/model', trust_remote_code=True, revision='<commit>')"Custom tokenizer implementation also requires remote code, separate from the model's remote code
Some repos ship both a custom modeling file and a custom tokenization file (tokenization_xyz.py). AutoTokenizer.from_pretrained needs its own trust_remote_code=True independent of the model call, and missing it on just the tokenizer call produces the same class of error even after the model itself loaded successfully.
Fix: Pass trust_remote_code=True consistently to every AutoClass call for that repo, not just AutoModel, after reviewing both the modeling and tokenization files.
python -c "from transformers import AutoTokenizer; AutoTokenizer.from_pretrained('org/model', trust_remote_code=True)"Organization policy or a security-hardened environment blocks trust_remote_code entirely by default
Some teams set an environment-wide policy (a wrapper around from_pretrained, or a monkeypatched default) that refuses trust_remote_code=True unconditionally as a blanket control, which surfaces as this same error persisting even when the flag is passed, because an internal guardrail is overriding it.
Fix: Check for internal wrapper libraries or security policies around model loading in your organization before assuming the flag itself is broken; the correct fix is usually to go through the reviewed, vendored-code exception process rather than bypassing the control.
Version pin of transformers is too new or too old relative to the pattern the repo's remote code expects
Remote code files sometimes call internal transformers APIs that changed between versions; a mismatch can produce a confusing secondary error after trust_remote_code=True is accepted, which looks similar to the original blocking error but is actually an incompatibility inside the custom code itself.
Fix: Check the model card for a recommended transformers version to pair with that specific remote code repo, since custom code is tested against a specific library version by its author, not against the general compatibility guarantees of upstream transformers.
Diagnostic commands
List the custom Python files in the repo before loading anything
python -c "from huggingface_hub import list_repo_files; print([f for f in list_repo_files('org/model') if f.endswith('.py')])"Any .py files listed here are code that will execute in your process if you set trust_remote_code=True. Review each one before proceeding.
Fetch and read the actual source before enabling the flag
curl -s https://huggingface.co/org/model/resolve/main/modeling_xyz.py
Read for suspicious patterns: network requests, subprocess calls, file system writes outside expected cache directories, or heavily obfuscated code. Clean, readable model-definition code (layers, attention, forward passes) is the expected and low-risk case.
Confirm which exact commit you are pinning
python -c "from huggingface_hub import HfApi; print(HfApi().model_info('org/model').sha)"Use this commit hash as your revision pin so a later, unreviewed update to the repo cannot silently swap in different code the next time your pipeline runs.
Stopping it from happening again
- Treat any trust_remote_code=True dependency as vendored third-party code: review it once, copy it into your own version-controlled location, and pin an exact revision rather than tracking 'main'.
- Establish an internal review and approval process for remote code before it is allowed in any regulated or production pipeline, similar to how you would review a new third-party library dependency.
- Prefer models with upstream transformers support when architecturally equivalent alternatives exist, reserving trust_remote_code for cases where it is genuinely necessary.
- Re-review the remote code any time you bump the pinned revision, since the whole point of remote code is that its behavior can change between commits.
When this becomes an architecture problem
If your regulated environment's policy genuinely cannot accept executing unreviewed third-party code, even after a one-time review, this stops being a per-model decision and becomes a governance process: a formal code review and sign-off step before any trust_remote_code model enters your environment, with the reviewed code vendored and frozen. That process, not the flag itself, is the actual control regulated customers need.
Frequently asked questions
Is trust_remote_code=True inherently unsafe?
It is a real expansion of your trust boundary: you are executing the model repository author's Python code in your process rather than only deserializing tensor data. It is not inherently malicious, most legitimate model authors ship clean code, but it removes the usual guarantee that only vetted library code runs, so it deserves a review step, especially in regulated environments.
Can I review the code without ever setting trust_remote_code=True?
Yes, and you should. Use huggingface_hub to list and download the repository's Python files directly, or browse them on the HuggingFace website, and read them before deciding to load the model at all.
How do I stop a remote code repo from changing behavior after I have already approved it?
Always pass an explicit revision (a commit SHA, not a branch name like main) alongside trust_remote_code=True, so from_pretrained always loads the exact reviewed version even if the upstream repo is updated later.
Is vendoring the code myself better than using trust_remote_code long term?
For production and regulated use, yes. Copying the reviewed modeling code into your own internal repository, under your own change control and code review process, removes the runtime dependency on trust_remote_code entirely and gives you an auditable, unchangeable artifact rather than a live pull from an external Hub.
Size it properly next time
Free calculators that prevent this class of failure before you provision hardware.
Air-Gapped LLM Deployment Checklist
A practical control checklist for deploying and maintaining large language models in a fully air-gapped environment, from initial staging through ongoing patching and drift detection.
Free ToolOn-Prem AI Deployment Checklist
A 30-point pre-deployment checklist covering use cases, hardware, security, model operations, and rollout for self-hosted enterprise LLMs.
Related problems
Model type or architecture not recognized when loading a new model
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.
401/403 Unauthorized pulling a gated model from HuggingFace
A 401 or 403 on a gated HuggingFace repo means the request reached the Hub but was rejected for authorization, not because the model does not exist. The three real causes are: you have not accepted the model's license on the web page with the account tied to your token, the token exists but was created without read access to gated repos, or the token is valid but was never actually passed to the download call (no HF_TOKEN in the environment, no login run). Fix by accepting the license, generating a token with the right scope, and exporting it where the client library will find it.
Model loading fails offline or in an air-gapped environment despite having local files
Passing a local path to from_pretrained does not guarantee an offline load, because transformers and related libraries (tokenizers, some model configs, auto-mapping code) can still issue background network calls to check for updates, fetch a referenced remote component, or resolve auto_map entries that point back at the original HuggingFace repo. The fix is to set HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1 explicitly, use a complete local snapshot directory (not just the weights file), and verify no config field still references a remote repo ID.
Model revision or commit not found when pinning a specific version
A revision not found error means the exact commit hash, branch name, or tag you specified does not exist in that repository, most often because it was copied from a different repo, mistyped, or refers to a commit that was later force-pushed away or a tag that was deleted or renamed by the repo maintainer. Fix it by listing the repo's actual available revisions and re-pinning to a real, current one, and build your own immutable mirror if you need guarantees beyond what the source repo's maintainers commit to preserving.
GuideSecuring Model Weights in the Enterprise
Secure model weights end to end: custody controls, encryption at rest, access policies, and exfiltration prevention for regulated AI deployments.
GuideAir-Gapped LLM Deployment Patterns That Actually Work
Air-gapped LLM deployment patterns that work: offline model transfer, update workflows, monitoring without telemetry, and CMMC-ready architectures.
GuideAir-Gapped Model Updates: A Patching Guide
Air-gapped model updates for enterprise AI: secure transfer procedures, hash verification, and staged rollout so patches never introduce risk.
Still stuck, or tired of fighting your own infrastructure?
Netray deploys and operates on-prem AI for regulated manufacturers and defense suppliers. We have debugged this stack in production, on air-gapped networks, at scale.