{"record":{"id":"7ffc069559f255e6","repo":"eyaltoledano/claude-task-master","slug":"failed-to-initialize-api-storage-falling-back-to","errorCode":null,"errorMessage":"Failed to initialize API storage, falling back to file storage:","messagePattern":"Failed to initialize API storage, falling back to file storage:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/tm-core/src/modules/storage/services/storage-factory.ts","lineNumber":275,"sourceCode":"\t}\n\n\t/**\n\t * Create a storage implementation with fallback\n\t * Tries API storage first, falls back to file storage\n\t */\n\tstatic async createWithFallback(\n\t\tconfig: Partial<IConfiguration>,\n\t\tprojectPath: string\n\t): Promise<IStorage> {\n\t\t// Try API storage if configured\n\t\tif (StorageFactory.isHamsterAvailable(config)) {\n\t\t\ttry {\n\t\t\t\tconst apiStorage = StorageFactory.createApiStorage(config);\n\t\t\t\tawait apiStorage.initialize();\n\t\t\t\treturn apiStorage;\n\t\t\t} catch (error) {\n\t\t\t\tconst logger = getLogger('StorageFactory');\n\t\t\t\tlogger.warn(\n\t\t\t\t\t'Failed to initialize API storage, falling back to file storage:',\n\t\t\t\t\terror\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to file storage\n\t\treturn StorageFactory.createFileStorage(projectPath, config);\n\t}\n}\n","sourceCodeStart":257,"sourceCodeEnd":286,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/storage/services/storage-factory.ts#L257-L286","documentation":"StorageFactory.createWithFallback() tries API-backed storage first; if creating or initializing it throws, it logs this warning (with the error) and falls back to local file storage, so the app keeps working but without the remote store.","triggerScenarios":"createWithFallback() invoked when API storage cannot be created/initialized — unreachable API endpoint, invalid/missing auth credentials in config, unsupported config shape, or network failure during initialize().","commonSituations":"Offline development machine, wrong API base URL or expired token in config, API server down during deploy, firewall blocking the endpoint in CI.","solutions":["Inspect the logged error object for the root cause (auth vs network vs config)","Verify API credentials and base URL in the storage config; test the endpoint with curl","Fix network/firewall issues so the API endpoint is reachable","Accept the file-storage fallback knowingly, or explicitly choose file storage to silence the warning"],"exampleFix":"// before\nconst storage = await StorageFactory.createWithFallback(config); // silently uses file storage\n// after\nconst storage = await StorageFactory.createWithFallback(config);\nif (storage.type !== 'api') console.warn('Running on file storage fallback; API storage failed to initialize');","handlingStrategy":"fallback","validationCode":"const reachable = await fetch(`${config.apiBaseUrl}/health`, { method: 'HEAD' }).then(r => r.ok).catch(() => false);\nif (!reachable) console.warn('API unreachable; expect file-storage fallback');","typeGuard":null,"tryCatchPattern":"const storage = await StorageFactory.createWithFallback(config);\nif (storage.constructor.name !== 'ApiStorage') {\n  logger.warn('Proceeding with file storage; API storage init failed — check credentials/network');\n}","preventionTips":["Verify API base URL and token in config before startup","Add a health-check ping to the storage API in deployment checks","Decide explicitly whether file-storage fallback is acceptable for your environment","Monitor logs for this warning to detect silent fallbacks"],"tags":["storage","fallback","api","network"],"backgroundTag":"storage-initialization-failure","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}