{"record":{"id":"3c51594d6f273890","repo":"microsoft/semantic-kernel","slug":"type-self-service-failed-to-transcribe-audio","errorCode":null,"errorMessage":"{type(self)} service failed to transcribe audio","messagePattern":"(.+?) service failed to transcribe audio","errorType":"exception","errorClass":"ServiceResponseException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/services/open_ai_handler.py","lineNumber":173,"sourceCode":"            )\n            self.store_usage(response)\n            return response\n        except Exception as ex:\n            raise ServiceResponseException(f\"Failed to edit image: {ex}\") from ex\n\n    async def _send_audio_to_text_request(self, settings: OpenAIAudioToTextExecutionSettings) -> Transcription:\n        \"\"\"Send a request to the OpenAI audio to text endpoint.\"\"\"\n        if not settings.filename:\n            raise ServiceInvalidRequestError(\"Audio file is required for audio to text service\")\n\n        try:\n            with open(settings.filename, \"rb\") as audio_file:\n                return await self.client.audio.transcriptions.create(\n                    file=audio_file,\n                    **settings.prepare_settings_dict(),\n                )\n        except Exception as ex:\n            raise ServiceResponseException(\n                f\"{type(self)} service failed to transcribe audio\",\n                ex,\n            ) from ex\n\n    async def _send_text_to_audio_request(\n        self, settings: OpenAITextToAudioExecutionSettings\n    ) -> _legacy_response.HttpxBinaryResponseContent:\n        \"\"\"Send a request to the OpenAI text to audio endpoint.\n\n        The OpenAI API returns the content of the generated audio file.\n        \"\"\"\n        try:\n            return await self.client.audio.speech.create(\n                **settings.prepare_settings_dict(),\n            )\n        except Exception as ex:\n            raise ServiceResponseException(\n                f\"{type(self)} service failed to generate audio\",","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/services/open_ai_handler.py#L155-L191","documentation":"Raised as ServiceResponseException in _send_audio_to_text_request when any exception occurs during client.audio.transcriptions.create or while opening the audio file. The handler catches all exceptions and wraps them, preserving the original in ex.__cause__. File I/O errors (file not found, permission denied) are also caught here because the open() call is inside the try block.","triggerScenarios":"The audio file path does not exist (FileNotFoundError), is not readable (PermissionError), is in an unsupported format, exceeds API limits, or the transcription API call fails due to network/rate-limit/content-filter issues.","commonSituations":"File path typo or deleted file; insufficient file permissions on the server; unsupported audio format (OpenAI supports mp3, wav, m4a, etc.); audio file too large; rate limit from many transcription requests.","solutions":["Inspect ex.__cause__ to distinguish file I/O errors from API errors","Verify the file path exists and the process has read permissions before calling","Ensure the audio format is supported (mp3, mp4, mpeg, mpga, m4a, wav, webm)","For API errors, check rate limits and file-size limits (25MB max for OpenAI transcription)"],"exampleFix":"# before\nresult = await service._send_audio_to_text_request(settings)\n# after — pre-validate file\nfrom pathlib import Path\np = Path(settings.filename)\nif not p.is_file():\n    raise FileNotFoundError(f'Audio file not found: {settings.filename}')\nresult = await service._send_audio_to_text_request(settings)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nSUPPORTED_FORMATS = {'.mp3', '.mp4', '.mpeg', '.mpga', '.m4a', '.wav', '.webm'}\np = Path(settings.filename)\nif not p.is_file():\n    raise FileNotFoundError(f'Audio file not found: {p}')\nif p.suffix.lower() not in SUPPORTED_FORMATS:\n    raise ValueError(f'Unsupported audio format: {p.suffix}')\nif p.stat().st_size > 25 * 1024 * 1024:\n    raise ValueError('Audio file exceeds 25MB limit')","typeGuard":null,"tryCatchPattern":"from semantic_kernel.exceptions import ServiceResponseException\n\ntry:\n    result = await service._send_audio_to_text_request(settings)\nexcept ServiceResponseException as e:\n    logger.error('Transcription failed: %s (cause: %s)', e, e.__cause__)\n    raise","preventionTips":["Validate file existence, format, and size before calling the transcription API","Ensure the application process has read access to the audio file path"],"tags":["openai","audio-to-text","transcription","file-io","catch-all"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}