FlowiseAI/Flowise · error · Error

Please set an API key for HuggingFace Hub in the environment

Error message

Please set an API key for HuggingFace Hub in the environment variable HUGGINGFACEHUB_API_KEY or in the apiKey field of the HuggingFaceInference constructor.

What it means

HuggingFaceInference constructor resolves apiKey as fields.apiKey then falls back to the HUGGINGFACEHUB_API_KEY environment variable; if both are falsy it throws. The check happens at construction, before any network call.

Source

Thrown at packages/components/nodes/llms/HuggingFaceInference/core.ts:67

    frequencyPenalty: number | undefined = undefined

    apiKey: string | undefined = undefined

    endpoint: string | undefined = undefined

    constructor(fields?: Partial<HFInput> & BaseLLMParams) {
        super(fields ?? {})

        this.model = fields?.model ?? this.model
        this.temperature = fields?.temperature ?? this.temperature
        this.maxTokens = fields?.maxTokens ?? this.maxTokens
        this.topP = fields?.topP ?? this.topP
        this.topK = fields?.topK ?? this.topK
        this.frequencyPenalty = fields?.frequencyPenalty ?? this.frequencyPenalty
        this.endpoint = fields?.endpoint ?? ''
        this.apiKey = fields?.apiKey ?? getEnvironmentVariable('HUGGINGFACEHUB_API_KEY')
        if (!this.apiKey) {
            throw new Error(
                'Please set an API key for HuggingFace Hub in the environment variable HUGGINGFACEHUB_API_KEY or in the apiKey field of the HuggingFaceInference constructor.'
            )
        }
    }

    _llmType() {
        return 'hf'
    }

    /** @ignore */
    async _call(prompt: string, options: this['ParsedCallOptions']): Promise<string> {
        const { HfInference } = await HuggingFaceInference.imports()
        const hf = new HfInference(this.apiKey)
        // v4 uses Inference Providers by default; only override if custom endpoint provided
        const hfClient = this.endpoint ? hf.endpoint(this.endpoint) : hf
        const obj: any = {
            parameters: {
                // make it behave similar to openai, returning only the generated text

View on GitHub (pinned to abe4a8601a)

Solutions

Set HUGGINGFACEHUB_API_KEY in the runtime environment (export / .env / container secret).
Attach a HuggingFace credential component in the node and pass its apiKey into fields.
Restart the process after setting the variable so it is read at construction.

Example fix

// before
const llm = new HuggingFaceInference({ model: 'mistralai/Mistral-7B' })
// after
const llm = new HuggingFaceInference({ model: 'mistralai/Mistral-7B', apiKey: process.env.HUGGINGFACEHUB_API_KEY })

Defensive patterns

Strategy: validation

Validate before calling

function resolveHfKey(fields?: { apiKey?: string }): string {
  const key = fields?.apiKey ?? process.env.HUGGINGFACEHUB_API_KEY
  if (!key) throw new Error('HUGGINGFACEHUB_API_KEY is not set')
  return key
}
const hf = new HuggingFaceInference({ apiKey: resolveHfKey(fields), ...fields })

Type guard

function hasHfKey(fields?: { apiKey?: string }): boolean {
  return Boolean(fields?.apiKey ?? process.env.HUGGINGFACEHUB_API_KEY)
}

Try / catch

try {
  const llm = new HuggingFaceInference(fields)
} catch (e) {
  if (/HUGGINGFACEHUB_API_KEY/.test((e as Error).message)) {
    // surface a credential-setup error to the user, do not retry
  }
  throw e
}

Prevention

Set HUGGINGFACEHUB_API_KEY in the deployment environment, not just locally.
Attach a credential component in Flowise rather than relying on env.
Add a startup health check that fails fast if the key is absent.
Use the exact variable name HUGGINGFACEHUB_API_KEY.

When it happens

Trigger: Instantiating the HuggingFaceInference LLM node without a credential and without HUGGINGFACEHUB_API_KEY exported in the process environment.

Common situations: Forgot to attach the HF credential to the node in Flowise; env var typo (e.g. HUGGINGFACE_API_KEY); deployed container without the secret mounted; .env not loaded at boot.

Related errors

AI-assisted analysis of FlowiseAI/Flowise@abe4a8601a (2026-08-12). Data as JSON: /api/errors/eba834069b835bc4. Report an issue: GitHub.