fix: support for IPv6 address literals in HOST env var

[kouellette]

Description

When pages would build URLs for API requests, process.env.HOST would be directly concatenated with process.env.PORT (e.g., 0.0.0.0:5055). This works for IPv4 address literals but does not work for IPv6 address literals because :::5055 for example is invalid. This commit adds a check if process.env.HOST contains a colon (:) and if so, wraps the host in square brackets. E.g., [::]:5055, which is valid. This allows for users to set the HOST environment variable to IPv6 address literals.

• Fixes Cannot set HOST env var to "::" to enable IPv6 binding #2612

How Has This Been Tested?

This was tested on a Debian 13 VM running kernel 6.12.48+deb13-amd64 for the server and a 13-inch 2022 MacBook Pro with the Arc browser Version 1.135.0 (75383), Chromium Engine Version 145.0.7632.110.

Tested by setting HOST env var to :: and another IPv6 literal and ensured pages loaded as expected and the error observed in the ticket was no longer occurring.

Screenshots / Logs (if applicable)

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract
• Database migration (if required)

Summary by CodeRabbit

• Refactor

  • Centralized host/port resolution for API requests across public settings, auth, collection, movie, and TV pages, using consistent URL construction.
  • Added safe handling for IPv6 hosts when building API endpoints.

• Chores

  • Improved server startup resilience by handling server startup errors more explicitly, logging a clear failure message, and exiting with a non-zero status when startup fails.

• Chores

  • Added a runtime dependency to support IP address handling.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Host and port resolution is centralized with IPv6 literal support, and server-side page requests use the helper. Server startup now captures the HTTP server and handles listen errors.

Changes

Runtime networking

Layer / File(s)	Summary
Host and port resolution src/utils/urlHelper.ts, package.json	Adds getHostAndPort(), formats IPv6 literals with brackets, and adds the ip-address runtime dependency.
Server-side API URLs src/pages/_app.tsx, src/pages/collection/..., src/pages/movie/..., src/pages/tv/...	Replaces inline host and port construction with getHostAndPort() for API requests.
Listen error handling server/index.ts	Stores the HTTP server returned by server.listen, logs listen errors, and exits with status 1.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Poem

I’m a rabbit fixing URLs with care,
Brackets for IPv6, tidy and fair,
Pages call one helper, neat and bright,
Server listens safely through the night,
Hopping off — all bindings now right! 🐇✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title accurately reflects the IPv6 HOST support change.
Linked Issues check	✅ Passed	IPv6 HOST literals are bracketed in generated URLs, matching #2612 and preventing invalid internal request URLs.
Out of Scope Changes check	✅ Passed	The server listen error handling and new dependency are directly tied to the IPv6 HOST fix, with no unrelated changes evident.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/utils/urlHelper.ts`:
- Around line 3-5: The current host-wrapping logic in src/utils/urlHelper.ts
blindly brackets any host containing ':' which double-brackets already-bracketed
IPv6 literals; update the guard in the host handling (the block that checks
host.includes(':')) to first detect if host already startsWith('[') and
endsWith(']') and only wrap with `[...]` when those brackets are absent, leaving
already-bracketed values unchanged.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 001f6b1 and ec96997.

📒 Files selected for processing (5)

• src/pages/_app.tsx
• src/pages/collection/[collectionId]/index.tsx
• src/pages/movie/[movieId]/index.tsx
• src/pages/tv/[tvId]/index.tsx
• src/utils/urlHelper.ts

[Copilot]

Pull request overview

Adds a shared helper for constructing internal HOST:PORT strings so server-side page requests can correctly target IPv6 address literals (by bracketing them) when building URLs for local API calls.

Changes:

• Introduced getHostAndPort() utility for consistent internal host/port formatting (including IPv6 bracketing).
• Updated server-side Axios calls in _app and several detail pages to use the new helper instead of inline process.env.HOST/process.env.PORT string concatenation.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/utils/urlHelper.ts	Adds centralized host/port formatting used for internal API URL construction.
src/pages/_app.tsx	Switches internal settings/user Axios requests to use the shared host/port helper.
src/pages/movie/[movieId]/index.tsx	Uses the shared host/port helper for server-side movie detail API calls.
src/pages/tv/[tvId]/index.tsx	Uses the shared host/port helper for server-side TV detail API calls.
src/pages/collection/[collectionId]/index.tsx	Uses the shared host/port helper for server-side collection detail API calls.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[0xSysR3ll]

Maybe overkill but this lib could help : https://www.npmjs.com/package/ip-address

[gauthier-th]

Maybe overkill but this lib could help : https://www.npmjs.com/package/ip-address

Yeah probably overkill. Worst case you don't properly configure the host address and the app crashes at startup?

[kouellette]

Maybe overkill but this lib could help : https://www.npmjs.com/package/ip-address

Yeah probably overkill. Worst case you don't properly configure the host address and the app crashes at startup?

Correct. However, I noticed this error wasn't being caught and logged so I updated the PR for this. Example logs when HOST=localhost:5055:

2026-03-06T01:13:30.188Z [info]: Starting Seerr version develop-local
2026-03-06T01:13:30.548Z [debug][Settings Migrator]: Checking migration '0001_migrate_hostname.js'...
2026-03-06T01:13:30.549Z [debug][Settings Migrator]: Checking migration '0002_migrate_apitokens.js'...
2026-03-06T01:13:30.550Z [debug][Settings Migrator]: Checking migration '0003_emby_media_server_type.js'...
2026-03-06T01:13:30.551Z [debug][Settings Migrator]: Checking migration '0004_migrate_region_setting.js'...
2026-03-06T01:13:30.551Z [debug][Settings Migrator]: Checking migration '0005_migrate_network_settings.js'...
2026-03-06T01:13:30.552Z [debug][Settings Migrator]: Checking migration '0006_remove_lunasea.js'...
2026-03-06T01:13:30.552Z [debug][Settings Migrator]: Checking migration '0007_migrate_arr_tags.js'...
2026-03-06T01:13:30.553Z [debug][Settings Migrator]: Checking migration '0008_migrate_blacklist_to_blocklist.js'...
2026-03-06T01:13:30.555Z [info][Notifications]: Registered notification agents
2026-03-06T01:13:30.558Z [info][Server]: Skipping starting the scheduled jobs as we have no Plex/Jellyfin/Emby servers setup yet
2026-03-06T01:13:30.652Z [error]: Listen error: getaddrinfo ENOTFOUND localhost:5055 {"errno":-3008,"code":"ENOTFOUND","syscall":"getaddrinfo","hostname":"localhost:5055","stack":"Error: getaddrinfo ENOTFOUND localhost:5055\n    at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:122:26)"}
 ELIFECYCLE  Command failed with exit code 1.
 ```

[coderabbitai]

🧹 Nitpick comments (1)

server/index.ts (1)

281-284: Consider using structured logging for consistency.

The error handler works correctly. For consistency with other logging calls in this file (e.g., lines 270, 276), consider using the structured format with a label property.

♻️ Suggested improvement

 httpServer.on('error', (err) => {
-  logger.error('Listen error:', err);
+  logger.error('Failed to start server', {
+    label: 'Server',
+    message: err.message,
+  });
   process.exit(1);
 });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@server/index.ts` around lines 281 - 284, Update the httpServer error handler
to use the same structured logging shape as other calls: replace the freeform
logger.error('Listen error:', err) in the httpServer.on('error', (err) => { ...
}) callback with a single structured call that passes an object including a
label (e.g., label: 'server:listen') and the error (e.g., err) so the log
matches the format used at lines like the other logger.error/logger.info calls;
ensure you only modify the logger.error invocation inside the
httpServer.on('error') handler to emit the label and error fields.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@server/index.ts`:
- Around line 281-284: Update the httpServer error handler to use the same
structured logging shape as other calls: replace the freeform
logger.error('Listen error:', err) in the httpServer.on('error', (err) => { ...
}) callback with a single structured call that passes an object including a
label (e.g., label: 'server:listen') and the error (e.g., err) so the log
matches the format used at lines like the other logger.error/logger.info calls;
ensure you only modify the logger.error invocation inside the
httpServer.on('error') handler to emit the label and error fields.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8c398c0f-bc14-4470-a352-fefc5235c195

📥 Commits

Reviewing files that changed from the base of the PR and between 9a1113f and 07e80dd.

📒 Files selected for processing (1)

• server/index.ts

[github-actions]

This PR is stale because it has been open 30 days with no activity. Please address the feedback or provide an update to keep it open.

[M0NsTeRRR]

Hey @kouellette can you review the two comments we did so we can merge your PR

[github-actions]

This PR is stale because it has been open 30 days with no activity. Please address the feedback or provide an update to keep it open.

[github-actions]

This pull request has merge conflicts. Please resolve the conflicts so the PR can be successfully reviewed and merged.

[M0NsTeRRR]

Otherwise LGTM

[M0NsTeRRR]

Thanks for your contribution @kouellette !

[cypress]

seerr    Run #3591

Run Properties:   Passed #3591  •  0adbf50b5c: fix: support for IPv6 address literals in HOST env var (#2614)

Project	seerr
Branch Review	develop
Run status	Passed #3591
Run duration	02m 50s
Commit	0adbf50b5c: fix: support for IPv6 address literals in HOST env var (#2614)
Committer	Kyle Ouellette
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	1
Pending	0
Skipped	0
Passing	33
View all changes introduced in this branch ↗︎