hiyouga/LlamaFactory · error · HTTPException

Invalid API key.

Error message

Invalid API key.

What it means

Before building the Megatron-Core adapter model, the workflow resolves model_type either from a local mca_config.json (saved with an mcore checkpoint) or via AutoConfig, and validates it against MCA_SUPPORTED_MODELS (constants.py:58: deepseek_v3, glm4_moe, llama, mistral, mixtral, qwen2, qwen2_vl, qwen2_5_vl, qwen3_vl, qwen3_vl_moe, qwen3, qwen3_moe, qwen3_next, qwen3_5, qwen3_5_moe). Anything else raises ValueError with a hint to upgrade the adapter, since newer adapter releases extend the set.

Source

Thrown at src/llamafactory/api/app.py:84

    torch_gc()


def create_app(chat_model: "ChatModel") -> "FastAPI":
    root_path = os.getenv("FASTAPI_ROOT_PATH", "")
    app = FastAPI(lifespan=partial(lifespan, chat_model=chat_model), root_path=root_path)
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
    api_key = os.getenv("API_KEY")
    security = HTTPBearer(auto_error=False)

    async def verify_api_key(auth: Annotated[HTTPAuthorizationCredentials | None, Depends(security)]):
        if api_key and (auth is None or auth.credentials != api_key):
            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid API key.")

    @app.get(
        "/v1/models",
        response_model=ModelList,
        status_code=status.HTTP_200_OK,
        dependencies=[Depends(verify_api_key)],
    )
    async def list_models():
        model_card = ModelCard(id=os.getenv("API_MODEL_NAME", "gpt-3.5-turbo"))
        return ModelList(data=[model_card])

    @app.post(
        "/v1/chat/completions",
        response_model=ChatCompletionResponse,
        status_code=status.HTTP_200_OK,
        dependencies=[Depends(verify_api_key)],
    )
    async def create_chat_completion(request: ChatCompletionRequest):

View on GitHub (pinned to f28afaf635)

Solutions

1. Upgrade the adapter: pip install -U mcore-adapter (newer versions support more model types)
2. Switch to a supported model_type (see MCA_SUPPORTED_MODELS in src/llamafactory/extras/constants.py)
3. If the checkpoint is mcore-native, ensure mca_config.json contains the correct hf_model_type field

Example fix

# before
model_name_or_path: google/gemma-3-4b  # model_type gemma3 not in set
# mca path -> ValueError

# after
pip install -U mcore-adapter
model_name_or_path: Qwen/Qwen3-8B  # qwen3 is supported

from transformers import AutoConfig
from llamafactory.extras.constants import MCA_SUPPORTED_MODELS
model_type = AutoConfig.from_pretrained(model_path).model_type
assert model_type in MCA_SUPPORTED_MODELS, (
    f'{model_type} unsupported by mcore_adapter; supported: {sorted(MCA_SUPPORTED_MODELS)}'
)

def mca_supports(model_name_or_path: str, trust_remote_code: bool = False) -> bool:
    from transformers import AutoConfig
    from llamafactory.extras.constants import MCA_SUPPORTED_MODELS
    return AutoConfig.from_pretrained(model_name_or_path, trust_remote_code=trust_remote_code).model_type in MCA_SUPPORTED_MODELS

try:
    run_exp()
except ValueError as e:
    if 'not supported by mcore_adapter' in str(e):
        raise SystemExit('Upgrade mcore-adapter (pip install -U mcore-adapter) or pick a supported model') from e
    raise

When it happens

Trigger: Pointing model_name_or_path at a model whose HF model_type is not in the set (e.g. gemma3, llama3 with a custom model_type, phi) while using the MCA trainer; or loading a raw mcore checkpoint whose mca_config.json lacks hf_model_type.

Common situations: Trying the Megatron path with a newly released model the installed adapter doesn't know; older mcore-adapter installs lacking recently added qwen3_5/qwen3_5_moe entries.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Invalid length
• `tensor_model_parallel_size` must be >= 1.
• `pipeline_model_parallel_size` must be >= 1.
• `expert_model_parallel_size` must be >= 1.
• `context_parallel_size` must be >= 1.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/87ce1a4348b52a6e. Report an issue: GitHub.