FlowiseAI/Flowise · error · Error

Please set an API key for HuggingFace Hub. Either configure

Error message

Please set an API key for HuggingFace Hub. Either configure it in the credential settings in the UI, or set the environment variable HUGGINGFACEHUB_API_KEY.

What it means

The ChatHuggingFace core wrapper validates apiKey in its constructor: it falls back from fields.apiKey to the HUGGINGFACEHUB_API_KEY environment variable, and throws if neither is set or if the key is whitespace-only. This is a hard pre-flight before any network call.

Source

Thrown at packages/components/nodes/chatmodels/ChatHuggingFace/core.ts:60

    endpointUrl: string | undefined = undefined

    includeCredentials: string | boolean | 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.stopSequences = fields?.stopSequences ?? this.stopSequences
        this.topP = fields?.topP ?? this.topP
        this.topK = fields?.topK ?? this.topK
        this.frequencyPenalty = fields?.frequencyPenalty ?? this.frequencyPenalty
        this.apiKey = fields?.apiKey ?? getEnvironmentVariable('HUGGINGFACEHUB_API_KEY')
        this.endpointUrl = fields?.endpointUrl
        this.includeCredentials = fields?.includeCredentials
        if (!this.apiKey || this.apiKey.trim() === '') {
            throw new Error(
                'Please set an API key for HuggingFace Hub. Either configure it in the credential settings in the UI, or set the environment variable HUGGINGFACEHUB_API_KEY.'
            )
        }
    }

    _llmType() {
        return 'hf'
    }

    invocationParams(options?: this['ParsedCallOptions']) {
        // Return parameters compatible with chatCompletion API (OpenAI-compatible format)
        const params: any = {
            temperature: this.temperature,
            max_tokens: this.maxTokens,
            stop: options?.stop ?? this.stopSequences,
            top_p: this.topP
        }
        // Include optional parameters if they are defined

View on GitHub (pinned to abe4a8601a)

Solutions

1. Add HUGGINGFACEHUB_API_KEY=hf_xxx to the Flowise server's .env (or container env) and restart.
2. Pass apiKey explicitly in the constructor fields when instantiating programmatically.
3. Confirm the variable name has no typo (it is HUGGINGFACEHUB_API_KEY, all caps).
4. For Flowise UI users, bind a HuggingFace credential so [83] supplies the key upstream.

Example fix

// before
const model = new ChatHuggingFace({ model: 'meta-llama/Llama-3-8B' }) // throws [84]

// after
const model = new ChatHuggingFace({
  model: 'meta-llama/Llama-3-8B',
  apiKey: process.env.HUGGINGFACEHUB_API_KEY
})

const apiKey = fields?.apiKey ?? process.env.HUGGINGFACEHUB_API_KEY
if (!apiKey || apiKey.trim() === '') {
  throw new Error('Set HUGGINGFACEHUB_API_KEY in the environment or pass apiKey in fields.')
}
const model = new ChatHuggingFace({ ...fields, apiKey })

function isValidHuggingFaceKey(key: unknown): key is string {
  return typeof key === 'string' && key.trim().length > 0
}

try {
  return new ChatHuggingFace(fields)
} catch (e) {
  if (e.message.includes('set an API key for HuggingFace Hub')) {
    process.env.HUGGINGFACEHUB_API_KEY = await promptUserForKey()
    return new ChatHuggingFace(fields)
  }
  throw e
}

When it happens

Trigger: Instantiating ChatHuggingFace with neither apiKey in the config nor HUGGINGFACEHUB_API_KEY in the process environment, or passing a key of only spaces. Distinct from [83] (node-layer) — this is the LangChain-style wrapper's own constructor guard.

Common situations: Self-hosted Flowise server where HUGGINGFACEHUB_API_KEY was never added to the .env (or container env); a unit test instantiating ChatHuggingFace without mocking the env; deployment that lost its env vars after a restart; CI runner missing the secret.

Related errors

• HuggingFace API key is required. Please configure it in the
• Please set an API key for HuggingFace Hub in the environment
• SEARXNG_API_BASE not set. You can set it as "SEARXNG_API_BAS
• Fireworks API key not found. Please set the FIREWORKS_API_KE
• HuggingFace API key is required. Please configure it in the

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