Troubleshooting 

Common issues 

Provider request fails 

Checklist:

  • Verify selected provider key (for example openai_api_key) is set.
  • Verify selected model value is valid for that provider.
  • Verify endpoint URL for custom/azure setups.
  • Review sys_log entries written by AiLogService.

HTTP 401 / 403 when fetching protected URL 

Checklist:

  • Enable basicAuthEnabled.
  • Set both basicAuthUsername and basicAuthPassword.
  • Re-test URL using HttpAuthUtility.

No statistics shown 

Checklist:

  • Ensure OpenAI key is configured (admin key preferred for org usage endpoint).
  • Check if API rate limit was hit.
  • Force refresh in consumer module (if available) or clear cache.
  • Confirm cache nsaiuniverse_statistics is available.

Unexpected model behavior 

  • Confirm active default model key.
  • Confirm per-provider model key.
  • Validate option values (temperature/tokens) are in expected range.

Operational guidance 

  • Use separate API keys per environment where possible.
  • Rotate keys after staff/vendor access changes.
  • Monitor usage trends and adjust limits before cost spikes.

Support information 

When escalating an issue, provide:

  • TYPO3 version
  • extension version
  • provider name and model
  • timestamp and scope/module
  • sanitized error message from logs