Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
The railways-docs project employs a multi-faceted approach to error handling, encompassing dedicated documentation for common platform errors, robust routing and server-side logic for handling non-existent pages (404s), and specific error responses within its API endpoints. This ensures a predictable and helpful user experience, whether a user is encountering a platform issue, navigating to an incorrect URL, or interacting with an API.
The system is designed to gracefully handle issues, from redirecting users from old error page URLs to providing structured JSON error messages from APIs. Server-side processes also include mechanisms to prevent catastrophic failures, such as try-catch blocks that allow partial content generation even if some source files fail to process.
Documented Errors
A key part of the error handling strategy is providing clear documentation for common issues users might face on the Railway platform. The documentation site has a dedicated "Errors" section under "Reference".
Sources: src/data/sidebar.ts:181-196
Error Reference Pages
The sidebar configuration explicitly defines a set of pages for specific, known errors. This provides users with a direct resource for troubleshooting.
This diagram shows the hierarchy of the error documentation section.
The following table lists the error pages defined in the sidebar:
| Error Page Title | Slug |
|---|---|
| Application Failed to Respond | /reference/errors/application-failed-to-respond |
| No Start Command Could Be Found | /reference/errors/no-start-command-could-be-found |
| 405 Method Not Allowed | /reference/errors/405-method-not-allowed |
| Unable to Generate a Build Plan | /reference/errors/nixpacks-was-unable-to-generate-a-build-plan |
| ENOTFOUND redis.railway.internal | /reference/errors/enotfound-redis-railway-internal |
Sources: src/data/sidebar.ts:182-195
Error Page Redirects
To maintain stable links and guide users from old or generic error pages to the correct, specific documentation, several permanent redirects are configured. For example, a generic fixing-common-errors guide is redirected to the main errors reference page.
| Source Path | Destination Path |
|---|---|
/guides/fixing-common-errors | /reference/errors |
/#application-failed-to-respond | /reference/errors/application-failed-to-respond |
/#post-requests-turn-into-get-requests | /reference/errors/405-method-not-allowed |
Sources: redirects.js:89-93, redirects.js:98-106
Page Not Found (404) Handling
The application uses a combination of Next.js middleware and server-side rendering logic to handle requests for pages that do not exist.
Request Flow for Non-Existent Pages
The following diagram illustrates the process from an incoming request to the final 404 page render.
This flow shows how both the middleware and the dynamic page's server-side props contribute to identifying and handling 404 errors.
-
Middleware Check: The
middleware.tsintercepts all incoming requests. It checks if the requested path (e.g.,/guides/my-page) exists in a pre-compiledpageUrlSet. If the path is not found, it callsNextResponse.next(), allowing Next.js to proceed to its default 404 handling.
Sources: src/middleware.ts:7, src/middleware.ts:18-22 -
Dynamic Page Fallback: If the middleware finds the path, it rewrites the URL to
/dynamic/[...slug]. ThegetServerSidePropsfunction insrc/pages/dynamic/[...slug].tsxthen attempts to find the corresponding page data fromallPages. If no page is found for the slug, it returns{ notFound: true }, which triggers Next.js to render the 404 page.
Sources: src/pages/dynamic/[...slug].tsx:61-67
API Error Handling
API routes include specific checks and error responses to handle invalid requests or internal processing issues.
Authorization Errors
The /api/export endpoint is protected and will return a 401 Unauthorized error if the request does not include the correct secret in the Authorization header.
This sequence diagram shows the authorization flow for the /api/export endpoint.
This is implemented by comparing the Authorization header against an environment variable.
Sources: src/pages/api/export.ts:7-10
Graceful Degradation in Content Processing
The /api/llms-docs.md.ts endpoint, which generates documentation for LLM consumption, includes a try...catch block when reading and processing individual markdown files. If an error occurs while processing a specific page (e.g., file not found, parsing error), the error is logged to the console, and the process continues to the next page. This prevents a single faulty file from causing the entire API request to fail.
// From src/pages/api/llms-docs.md.ts
pages.forEach((page: IPage) => {
try {
// ... read and process markdown file
} catch (error) {
console.error(`Error processing ${page.slug}:`, error);
// Still include basic information even if we can't read the file
content += `# ${page.title}\n`;
content += `Source: https://docs.railway.com${page.slug}\n\n`;
content += "\n";
}
});
Sources: src/pages/api/llms-docs.md.ts:71-122
User-Facing Error Guidance
In addition to formal documentation, the project provides user-facing guidance through other mechanisms.
FAQ for Common Errors
The public/static/faq.json file contains a list of common questions and answers, many of which relate to application errors like Bad Gateway. This serves as a quick reference for users encountering frequent problems.
| Error Key | Sample Question | Link |
|---|---|---|
bad-gateway | My app works locally but says Bad Gateway when I deploy? | https://docs.railway.com/deploy/exposing-your-app |
plugin-connection | Why can't I connect to my plugin? | |
un-ban | Why does it say 'end of the line'? |
Sources: public/static/faq.json:2-9, public/static/faq.json:62-68, public/static/faq.json:84-90
Search Results Fallback
The search results component has a minor but notable error handling case. If a search result's chapter is unexpectedly null, it falls back to displaying the first hierarchy level (hits[0]?.hierarchies[0]) instead of rendering the literal string "null", preventing broken UI text.