{"record":{"id":"69202d65b303c9eb","repo":"mastra-ai/mastra","slug":"telegram-installation-secrets-are-encrypted-at-res","errorCode":null,"errorMessage":"Telegram installation secrets are encrypted at rest, but no encryption key is configured. Set `encryptionKey` on TelegramProvider or MASTRA_ENCRYPTION_KEY.","messagePattern":"Telegram installation secrets are encrypted at rest, but no encryption key is configured\\. Set `encryptionKey` on TelegramProvider or MASTRA_ENCRYPTION_KEY\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"channels/telegram/src/install-store.ts","lineNumber":68,"sourceCode":"    const records = await this.storage.listInstallations(PLATFORM);\n    return records.map(r => this.#fromRecord(r));\n  }\n\n  /** Remove an agent's installation, if present. */\n  async deleteByAgent(agentId: string): Promise<void> {\n    const record = await this.storage.getInstallationByAgent(PLATFORM, agentId);\n    if (record) await this.storage.deleteInstallation(record.id);\n  }\n\n  #enc(value: string | undefined): string | undefined {\n    return value && this.encryptionKey ? encrypt(value, this.encryptionKey) : value;\n  }\n\n  #dec(value: string | undefined): string | undefined {\n    if (!value) return value;\n    if (!this.encryptionKey) {\n      if (isEncrypted(value)) {\n        throw new Error(\n          'Telegram installation secrets are encrypted at rest, but no encryption key is configured. Set `encryptionKey` on TelegramProvider or MASTRA_ENCRYPTION_KEY.',\n        );\n      }\n      return value;\n    }\n    return decrypt(value, this.encryptionKey);\n  }\n\n  #toRecord(install: TelegramInstallation): ChannelInstallation {\n    const data: TelegramInstallationData = {\n      botToken: this.#enc(install.botToken),\n      secretToken: this.#enc(install.secretToken),\n      username: install.username,\n      webhookUrl: install.webhookUrl,\n      commands: install.commands,\n    };\n    return {\n      id: install.id,","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/channels/telegram/src/install-store.ts#L50-L86","documentation":"Telegram installation secrets (bot tokens) are encrypted at rest with encrypt(). When the store reads a record whose secret carries the encrypted marker but the TelegramProvider/store has no encryptionKey (neither constructor option nor MASTRA_ENCRYPTION_KEY), it cannot decrypt, so it throws instead of returning ciphertext as if it were a token. Passing ciphertext through unchanged would produce hopeless downstream auth failures, hence the fail-fast.","triggerScenarios":"Loading/reading a stored Telegram installation whose secret was saved encrypted, while the current process was started without MASTRA_ENCRYPTION_KEY and without encryptionKey on TelegramProvider.","commonSituations":"Deploying to a new environment (CI, staging) where the MASTRA_ENCRYPTION_KEY env var wasn't copied; rotating keys infra and forgetting the env var; running locally against a prod database whose records were encrypted.","solutions":["Set MASTRA_ENCRYPTION_KEY in the environment to the same key used when the installation was saved.","Pass encryptionKey explicitly: new TelegramProvider({ encryptionKey }) / store option.","If the key is truly lost, delete the encrypted installation records and re-install the Telegram bot to re-encrypt with the new key.","Keep the key stable across environments (secret manager) to avoid re-encryption churn."],"exampleFix":"// before\nconst provider = new TelegramProvider({});\n// after\nconst provider = new TelegramProvider({\n  encryptionKey: process.env.MASTRA_ENCRYPTION_KEY,\n});","handlingStrategy":"validation","validationCode":"const encryptionKey = process.env.MASTRA_ENCRYPTION_KEY;\nif (!encryptionKey) {\n  throw new Error('MASTRA_ENCRYPTION_KEY must be set to read Telegram installations');\n}\nconst provider = new TelegramProvider({ encryptionKey });","typeGuard":null,"tryCatchPattern":"try {\n  const botToken = store.getBotToken(agentId);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('no encryption key is configured')) {\n    console.error('Set MASTRA_ENCRYPTION_KEY to the key used when this installation was saved');\n  } else throw e;\n}","preventionTips":["Provision MASTRA_ENCRYPTION_KEY identically across dev/staging/prod via a secret manager.","Add a startup health check that fails boot when the key is absent but encrypted records exist.","Back up the key securely; if lost, encrypted installations must be re-created."],"tags":["telegram","encryption","missing-env-var","configuration"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}