Directus AI Chat Bug: PUBLIC_URL Path Issues

by Admin 45 views
Directus AI Chat Bug: PUBLIC_URL Path Issues

Hey everyone! Today, we're diving deep into a rather frustrating bug that's popped up with the new AI chat feature in Directus version 11.14.0. If you're running your Directus instance with a PUBLIC_URL that includes a path, like https://example.com/api, you might find that the AI chat just isn't working as expected. It's a bummer, I know, but stick around and we'll break down exactly what's going on and how you might be able to navigate this.

The Core Problem: Pathing Mismatch

So, the main issue we're seeing here is a pathing mismatch when Directus tries to communicate with its AI chat service. When you configure your PUBLIC_URL to include a specific path, such as https://example.com/api, Directus is supposed to prepend this to all its outgoing requests. However, it seems like the AI chat feature isn't quite picking up on this configuration correctly. Instead of sending requests to https://example.com/api/ai/chat, it's attempting to send them to https://example.com/ai/chat. This might sound like a minor detail, but in the world of web requests and server routing, it's a huge difference. The server is looking for the AI chat endpoint at the root of the domain, not within the /api path you've specified. This results in a classic 404 Not Found error, leaving your AI chat feature dead in the water. It’s a real head-scratcher when you’ve got your setup just right, and suddenly a new feature throws a wrench in the works. We've all been there, right? You spend ages configuring your environment, making sure everything is perfect, and then bam – a simple configuration setting causes a major feature to fail. This particular bug highlights how crucial proper URL handling is, especially in complex, containerized environments where different services might be routed through specific paths.

Why This Happens: A Closer Look at Directus and Docker

Let's get a bit more technical, guys. When you're running Directus in a self-hosted Docker setup, you often use a reverse proxy (like Nginx or Traefik) to manage incoming traffic and route it to the correct service. Setting PUBLIC_URL to https://example.com/api tells Directus where it lives on the internet. This is vital for generating correct absolute URLs for things like email notifications, API responses, and, as we're seeing, for internal service communication. The AI chat feature, being a newer addition, likely makes its API calls based on a hardcoded assumption or a different configuration parsing logic than the rest of Directus. If the PUBLIC_URL is https://example.com/api, Directus should internally construct URLs like https://example.com/api/rest/v1/... for its own API endpoints. However, when it tries to reach its own AI service, it seems to be bypassing the PUBLIC_URL prefix or incorrectly applying it, leading to the /ai/chat path instead of the expected /api/ai/chat. This discrepancy often arises when different parts of an application are developed independently or integrated at different times. The core Directus app might correctly use the PUBLIC_URL for most operations, but a new module like AI chat might have its own internal logic that doesn't fully respect the global configuration, especially when that configuration involves a subpath. In a Dockerized environment, this can be further complicated by how your reverse proxy is configured. If the proxy is set up to forward requests to /api to the Directus container, but the AI chat requests are going directly to /ai/chat, the proxy won't know where to send them, hence the 404. It’s a classic case of a configuration setting that works for most things but trips up a specific, newer feature. Understanding your Docker network and proxy configuration is key here, as it dictates how these paths are ultimately resolved.

How to Reproduce the Bug: Step-by-Step

Reproducing this bug is pretty straightforward if you have the right setup. It’s all about that PUBLIC_URL configuration. Follow these steps, and you’ll likely see the AI chat fail:

  1. Configure PUBLIC_URL with a Path: This is the crucial first step. You need to set your PUBLIC_URL environment variable in your Directus configuration to include a path. For example, in your .env file or Docker Compose configuration, you would have something like:

    PUBLIC_URL=https://yourdomain.com/api

    Make sure this URL is accessible and correctly configured to point to your Directus instance, potentially through a reverse proxy. If you're using Docker, this would likely be part of your docker-compose.yml or the environment variables passed to your Directus service.

  2. Ensure AI Chat is Enabled: Make sure you have the AI chat feature enabled in your Directus project. This usually involves setting up the necessary API keys and potentially configuring the AI model provider within your Directus settings.

  3. Access the AI Chat Interface: Once Directus is running with the specified PUBLIC_URL and the AI chat is configured, navigate to the AI chat interface within your Directus project. This is typically found in the main navigation or a dedicated section for AI features.

  4. Send a Message: Try sending a simple message to the AI chat. It could be anything – a question, a command, or just a greeting. Observe the network requests being made by your browser. You should see a POST request being sent to an endpoint like https://yourdomain.com/ai/chat.

  5. Observe the 404 Error: The request will fail, and you’ll likely see a 404 Not Found error in your browser's developer tools (under the Network tab) or directly in the Directus UI indicating that the chat feature is unavailable. The request should have gone to https://yourdomain.com/api/ai/chat if the PUBLIC_URL were correctly interpreted by the AI chat module.

This simple reproduction path clearly demonstrates the bug. It's not a complex setup; it's a fundamental issue with how the AI chat feature handles the PUBLIC_URL when it contains a subpath. This makes it difficult for users who intentionally configure their environments this way for various reasons, such as running multiple applications on the same domain or for security considerations. The fact that it's a version-specific bug (v11.14.0) also suggests it might be a regression or a newly introduced issue in that particular release. It’s a good reminder to always test new features thoroughly after an upgrade, especially in non-standard configurations.

Directus Version and Hosting Strategy Details

We're specifically looking at Directus version v11.14.0 for this bug. This is important because bugs are often version-specific. A feature that works in one version might break in the next, or a bug might be introduced and then fixed later. So, if you're on a different version, you might not be experiencing this exact issue. The fact that it's present in v11.14.0 means it's something the developers will need to address for users on this release.

Our hosting strategy is Self-Hosted (Custom). This is a key piece of information. When you self-host Directus, you have a lot more control over your environment, including how you configure networking, reverse proxies, and environment variables like PUBLIC_URL. This contrasts with Directus Cloud, where many of these configurations are managed for you. Because this bug is occurring in a self-hosted environment with a custom PUBLIC_URL path, it points towards an interaction between Directus's internal routing logic and how the external URL is being parsed or utilized by the AI chat module. It’s possible that in a standard setup (PUBLIC_URL=https://example.com), everything works fine because the AI chat module correctly appends /ai/chat to the root. However, when the base URL itself already includes a path component (/api), the module fails to correctly prepend this base path, leading to the incorrect request URL. This kind of bug often requires a developer to trace the request flow within the Directus codebase, specifically looking at how the PUBLIC_URL environment variable is accessed and used when making requests to the AI service. It's a classic self-hosted challenge: more power, but also more responsibility (and sometimes, more bugs to squash!). The custom nature of the hosting also means that external factors like your specific Docker network configuration, the type of reverse proxy you're using, and its specific routing rules could potentially play a role, although the core issue seems to lie within Directus itself.

Database Agnosticism

While the bug report mentions _No response_ for the database, it's worth noting that Directus is designed to be database-agnostic. This means the underlying database (PostgreSQL, MySQL, SQLite, etc.) is unlikely to be the cause of this particular issue. The problem lies in how the Directus application handles its public-facing URL configuration and routes requests for its internal services. So, you can probably rule out any database-specific troubleshooting for this AI chat bug. Focus your efforts on the PUBLIC_URL setting and how Directus interprets it.

Potential Workarounds and Solutions

Okay, so what can you do if you're hitting this wall? While a direct fix from the Directus team is the ideal solution, there are a couple of potential workarounds you could consider:

  1. Change PUBLIC_URL (If Possible): The most straightforward (though perhaps not ideal) solution is to temporarily remove the path from your PUBLIC_URL. If your setup allows, changing PUBLIC_URL back to something like https://example.com would likely resolve the AI chat issue. This bypasses the bug entirely. However, we understand that changing PUBLIC_URL might break other parts of your application or integrations, so this isn't always a feasible option. It's a quick fix but might require a cascading set of changes elsewhere.

  2. Reverse Proxy Magic: If you must keep the path in your PUBLIC_URL, you could potentially configure your reverse proxy to handle the AI chat requests differently. This is more advanced. You might set up a rule that specifically forwards requests to https://example.com/ai/chat to the correct Directus endpoint even though Directus is configured with /api. This involves deep knowledge of your proxy server (Nginx, Traefik, etc.) and how it routes traffic. For example, in Nginx, you might add a location block specifically for /ai/chat that overrides the default /api forwarding. This is essentially telling the outside world that /ai/chat is a valid path, even if Directus thinks it should be /api/ai/chat. It's a bit of a workaround on the infrastructure level rather than fixing the app itself, but it can get the job done.

  3. Wait for a Directus Fix: The best long-term solution is for the Directus core team to address this bug. Keep an eye on the official Directus GitHub repository for issue reports and pull requests related to AI chat and PUBLIC_URL handling. If you haven't already, consider reporting the bug yourself or adding a comment to an existing report. This helps the developers prioritize and fix the issue for everyone.

Conclusion and Next Steps

This bug with Directus v11.14.0 and the PUBLIC_URL path is a clear example of how specific configurations can sometimes trip up new features. It's a pain point for self-hosters who utilize subpath configurations. The core issue is the AI chat module's inability to correctly interpret and use the PUBLIC_URL when it includes a path segment, leading to 404 errors. We've walked through how to reproduce it, discussed the hosting context, and explored potential workarounds. The most important thing is to stay informed by following the Directus GitHub issues. If you encounter this, report it! Your contribution helps the whole community. Hopefully, a fix will be rolled out soon in a future Directus release, making the AI chat feature robust for all users, regardless of their PUBLIC_URL setup. Happy Directusing, and let's hope for a swift resolution to this AI chat conundrum!