Troubleshooting

Common issues

Provider request fails

Checklist:

  • Verify the target provider row exists and is enabled in AI Foundation → AI Providers.

  • Run Test connection from the AI Providers drawer.

  • Verify model id and endpoint URL on the provider row (custom/OpenAI-compatible).

  • 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 nst3af_statistics is available.

Unexpected model behavior

  • Confirm the default provider in AI Providers matches the feature you expect.

  • Confirm per-provider model id on the provider row.

  • Validate temperature and token settings on the provider row.

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