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

The private _prepareHFInference helper re-validates the API key before constructing the InferenceClient: if apiKey is falsy or trims to empty, it throws the same 'HuggingFace API key is required' message as [83]/[84]. This is a defense-in-depth check because the key is read fresh from this.apiKey at request time, not just at construction.

Source

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

            if (error?.message?.includes('endpointUrl') || error?.message?.includes('third-party provider')) {
                throw new Error(
                    `Cannot use custom endpoint with model "${this.model}" that includes a provider. Please leave the Endpoint field blank in the UI. Original error: ${error.message}`
                )
            }
            if (error?.message?.includes('Invalid username or password') || error?.message?.includes('authentication')) {
                throw new Error(
                    `HuggingFace API authentication failed. Please verify your API key is correct and starts with "hf_". Original error: ${error.message}`
                )
            }
            throw error
        }
    }

    /** @ignore */
    private async _prepareHFInference() {
        if (!this.apiKey || this.apiKey.trim() === '') {
            console.error('[ChatHuggingFace] API key validation failed: Empty or undefined')
            throw new Error('HuggingFace API key is required. Please configure it in the credential settings.')
        }

        const { InferenceClient } = await HuggingFaceInference.imports()
        // Use InferenceClient for chat models (works better with Inference Providers)
        const client = new InferenceClient(this.apiKey)

        // Don't override endpoint if model uses a provider (contains ':') or if endpoint is router-based
        // When using Inference Providers, endpoint should be left blank - InferenceClient handles routing automatically
        if (
            this.endpointUrl &&
            !this.model.includes(':') &&
            !this.endpointUrl.includes('/v1/chat/completions') &&
            !this.endpointUrl.includes('router.huggingface.co')
        ) {
            return client.endpoint(this.endpointUrl)
        }

        // Return client without endpoint override - InferenceClient will use Inference Providers automatically

View on GitHub (pinned to abe4a8601a)

Solutions

Ensure apiKey is set to a non-empty, non-whitespace 'hf_' key at the moment of the request, not just at construction.
Audit any code that mutates model.apiKey after init.
If using credential rotation, swap the key atomically rather than clearing then setting.
Rebind the credential component and restart the chatflow to reload the key.

Example fix

// before
model.apiKey = '   ' // truthy at assign, fails trim() in _prepareHFInference
await model.invoke(prompt) // throws [89]

// after
model.apiKey = process.env.HUGGINGFACEHUB_API_KEY?.trim()
if (!model.apiKey) throw new Error('config error: missing key')
await model.invoke(prompt)

Defensive patterns

Strategy: validation

Validate before calling

function assertKeyAtRequestTime(apiKey) {
  if (!apiKey || apiKey.trim() === '') {
    throw new Error('apiKey became empty before the HF request; check mutations of model.apiKey.')
  }
}
// call right before invoking
assertKeyAtRequestTime(model.apiKey)

Type guard

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

Try / catch

try {
  return await model.invoke(prompt)
} catch (e) {
  if (e.message === 'HuggingFace API key is required. Please configure it in the credential settings.') {
    model.apiKey = (await reloadCredential()).huggingFaceApiKey
    return await model.invoke(prompt)
  }
  throw e
}

Prevention

Never mutate model.apiKey after construction; rebuild the model instead.
Treat the key as immutable per request lifecycle.
When rotating credentials, swap atomically — clear-and-set invites a race with this guard.
Unit-test the per-request validation path, not just the constructor.

When it happens

Trigger: this.apiKey was set to a whitespace-only string, or a code path mutated apiKey to empty/undefined after construction but before a request. Distinguishes from [84] (constructor) by being the per-request guard inside _prepareHFInference.

Common situations: Hot-reload or model-reuse where the field was cleared; a subclass or wrapper that resets apiKey between calls; a credential refresh that nulls the field before reassigning; whitespace-only keys that passed an earlier truthy check but fail the trim() check here.

Related errors

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