eyaltoledano/claude-task-master · error

Invalid provider hint received: ${providerHint}

Error message

Invalid provider hint received: ${providerHint}

What it means

A defensive guard in setModel reached when a providerHint string was supplied but matches none of the CUSTOM_PROVIDERS constants (OPENAI_COMPATIBLE, LMSTUDIO, CODEX_CLI, GEMINI_CLI, etc.). The message claims this 'should not happen with our constants' — it fires when an unrecognized/misspelled hint is passed programmatically or a CLI flag maps to an unknown value.

Source

Thrown at scripts/modules/task-manager/models.js:678

					// Only preserve baseURL if we're already using OPENAI_COMPATIBLE
					const existingBaseURL =
						currentProvider === CUSTOM_PROVIDERS.OPENAI_COMPATIBLE
							? getBaseUrlForRole(role, projectRoot)
							: null;

					const resolvedBaseURL = baseURL || existingBaseURL;
					if (!resolvedBaseURL) {
						throw new Error(
							`Base URL is required for OpenAI-compatible providers. Please provide a baseURL.`
						);
					}
					warningMessage = `Warning: Custom OpenAI-compatible model '${modelId}' set with base URL '${resolvedBaseURL}'. Taskmaster cannot guarantee compatibility. Ensure your API endpoint follows the OpenAI API specification.`;
					report('warn', warningMessage);
					// Store the computed baseURL so it gets saved in config
					computedBaseURL = resolvedBaseURL;
				} else {
					// Invalid provider hint - should not happen with our constants
					throw new Error(`Invalid provider hint received: ${providerHint}`);
				}
			}
		} else {
			// No hint provided (flags not used)
			if (modelData) {
				// Found internally, use the provider from the internal list
				determinedProvider = modelData.provider;
				report(
					'info',
					`Model ${modelId} found internally with provider ${determinedProvider}.`
				);
			} else {
				// Model not found and no provider hint was given
				return {
					success: false,
					error: {
						code: 'MODEL_NOT_FOUND_NO_HINT',
						message: `Model ID "${modelId}" not found in Taskmaster's supported models. If this is a custom model, please specify the provider using --openrouter, --ollama, --bedrock, --azure, --vertex, --lmstudio, --openai-compatible, --gemini-cli, or --codex-cli.`

View on GitHub (pinned to c0c98d367c)

Solutions

1. Use only exported CUSTOM_PROVIDERS constants as hints, never raw strings
2. Check the spelling/exact value of the providerHint against CUSTOM_PROVIDERS (e.g. CUSTOM_PROVIDERS.OPENAI_COMPATIBLE)
3. Update the package if an older version is passing a hint constant that was renamed/removed
4. If the model is from a known provider, drop the hint and let setModel resolve the provider from its internal supported-models list

Example fix

// before
await setModel(projectRoot, 'main', 'my-model', { providerHint: 'openai' });
// after
import { CUSTOM_PROVIDERS } from './constants.js';
await setModel(projectRoot, 'main', 'my-model', { providerHint: CUSTOM_PROVIDERS.OPENAI_COMPATIBLE });

import { CUSTOM_PROVIDERS } from './constants.js';
function assertValidHint(hint) {
  const valid = Object.values(CUSTOM_PROVIDERS);
  if (hint != null && !valid.includes(hint)) {
    throw new Error(`providerHint must be one of: ${valid.join(', ')}; got "${hint}"`);
  }
}

const isProviderHint = (v) => v == null || Object.values(CUSTOM_PROVIDERS).includes(v);

try {
  await setModel(projectRoot, role, modelId, { providerHint: hint });
} catch (err) {
  if (/Invalid provider hint/.test(err.message)) {
    console.error(`Hint "${hint}" unknown. Use a CUSTOM_PROVIDERS constant.`);
  } else throw err;
}

When it happens

Trigger: Calling setModel internally with a providerHint value that is not one of the CUSTOM_PROVIDERS constants — e.g. passing 'custom', 'openai', a typo like 'openai_compatable', or a stale constant from an older version.

Common situations: Plugin/script integration calling the API directly with a hand-written hint string; version mismatch where old code passes hints removed from CUSTOM_PROVIDERS; mixing up provider names ('openai-compatible' vs 'openai').

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Base URL is required for OpenAI-compatible providers. Please
• ${this.name} API key is required
• ${this.name} Model ID is required
• MODEL_NOT_FOUND_NO_HINT
• PROVIDER_UNDETERMINED

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/ec3fe30975ca3b7c. Report an issue: GitHub.