FlowiseAI/Flowise · error · Error

HuggingFace API key is required. Please configure it in the

Error message

HuggingFace API key is required. Please configure it in the credential settings.

What it means

ChatHuggingFace's init reads the API key via getCredentialParam('huggingFaceApiKey', ...) from the node's bound credential. If that lookup returns a falsy value, Flowise refuses to construct the model. A console.error line is emitted before the throw to mark it as a credential-validation failure.

Source

Thrown at packages/components/nodes/chatmodels/ChatHuggingFace/ChatHuggingFace.ts:131

    }

    async init(nodeData: INodeData, _: string, options: ICommonObject): Promise<any> {
        const model = nodeData.inputs?.model as string
        const temperature = nodeData.inputs?.temperature as string
        const maxTokens = nodeData.inputs?.maxTokens as string
        const topP = nodeData.inputs?.topP as string
        const hfTopK = nodeData.inputs?.hfTopK as string
        const frequencyPenalty = nodeData.inputs?.frequencyPenalty as string
        const endpoint = nodeData.inputs?.endpoint as string
        const cache = nodeData.inputs?.cache as BaseCache
        const stop = nodeData.inputs?.stop as string

        const credentialData = await getCredentialData(nodeData.credential ?? '', options)
        const huggingFaceApiKey = getCredentialParam('huggingFaceApiKey', credentialData, nodeData)

        if (!huggingFaceApiKey) {
            console.error('[ChatHuggingFace] API key validation failed: No API key found')
            throw new Error('HuggingFace API key is required. Please configure it in the credential settings.')
        }

        if (!huggingFaceApiKey.startsWith('hf_')) {
            console.warn('[ChatHuggingFace] API key format warning: Key does not start with "hf_"')
        }

        const obj: Partial<HFInput> = {
            model,
            apiKey: huggingFaceApiKey
        }

        if (temperature) obj.temperature = parseFloat(temperature)
        if (maxTokens) obj.maxTokens = parseInt(maxTokens, 10)
        if (topP) obj.topP = parseFloat(topP)
        if (hfTopK) obj.topK = parseFloat(hfTopK)
        if (frequencyPenalty) obj.frequencyPenalty = parseFloat(frequencyPenalty)
        if (endpoint) obj.endpointUrl = endpoint
        if (stop) {

View on GitHub (pinned to abe4a8601a)

Solutions

Open the node's Credential setting and bind a HuggingFace credential whose huggingFaceApiKey field is filled.
If the credential exists but is empty, edit it and paste a key starting with 'hf_'.
Verify the credential component type matches what ChatHuggingFace expects (HuggingFace API key component).
Re-import or recreate the credential if the chatflow was copied across workspaces.

Example fix

// before: nodeData.credential === ''

// after: bind credential in UI, or programmatically
nodeData.credential = 'huggingface-cred-id'
// credential component has field huggingFaceApiKey = 'hf_xxx'

Defensive patterns

Strategy: validation

Validate before calling

const credentialData = await getCredentialData(nodeData.credential ?? '', options)
const key = getCredentialParam('huggingFaceApiKey', credentialData, nodeData)
if (!key) {
  throw new Error('ChatHuggingFace node is missing a bound HuggingFace credential. Bind one in the node settings.')
}

Type guard

function hasHuggingFaceCredential(cred: unknown): cred is { huggingFaceApiKey: string } {
  return typeof (cred as any)?.huggingFaceApiKey === 'string' && (cred as any).huggingFaceApiKey.length > 0
}

Try / catch

try {
  return await initChatModel(nodeData, options)
} catch (e) {
  if (e.message === 'HuggingFace API key is required. Please configure it in the credential settings.') {
    return { error: 'Bind a HuggingFace credential with an hf_ key, then retry.' }
  }
  throw e
}

Prevention

Always bind a credential component before saving a ChatHuggingFace node.
Use the credential type designed for HuggingFace, not a generic key.
When copying chatflows between workspaces, copy the credentials too.
Validate key presence in a pre-deploy lint of the chatflow JSON.

When it happens

Trigger: nodeData.credential is empty/unbound, the bound credential component lacks a huggingFaceApiKey field, the credential exists but the field is blank, or the credential name does not resolve in the current workspace. Distinct from core.ts:84 because this is the Flowise node-layer check before the LangChain wrapper is built.

Common situations: User added the ChatHuggingFace node but did not attach a HuggingFace credential component; selected a credential of the wrong type; renamed/deleted the credential in another workspace; copied a chatflow JSON between instances without copying credentials.

Related errors

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