sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-10-19 03:59:05 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: add common issues to the troubleshooting hub and fill out the area tiles (#1039)

Browse Source 
* docs: add common issues to the troubleshooting hub and fill out the area tiles

Lead the Troubleshooting hub with a table of the issues support sees most
often, and give each area tile the sections a reader actually needs,
including a new Reverse Proxy tile.

Add the case where a teammate signs in and gets their own account to the
pending approval page, with sign-in domains as the fix.

List the headings rendered by the troubleshooting components in "On this
page", which previously only showed Markdown headings.

* docs: address review on account-access and support wording

- Personal-address teammate: drop the direct-invite advice, since a user
  who already has an account can't be invited; point to the work address
  or NetBird Support instead.
- Support audience: say NetBird Support is mainly for paying Cloud
  customers and commercial-license deployments, consistently across the
  troubleshooting hub, the support page, and the report-bug page.

* docs: align the troubleshooting hub table and rework Still stuck

- Common issues table: fixed 50/50 columns, with the Start here column
  padded to line up with the right-hand area tiles at any width.
- Still stuck: match the width and side padding of the tiles, center the
  title and buttons, and put a short audience note under each button.
  The report hint moves to its own line above the links, with a new
  Debug bundle link.
This commit is contained in:
Bruno Mercier Costa
2026-10-15 15:35:51 +02:00
committed by GitHub
parent eb9b675cb2
commit 6f6ad52072
7 changed files with 237 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mdx/rehype.mjs
+20 -1
View File
@@ -165,11 +165,30 @@ function rehypeAddMDXExports(getExports) {
} }
} }
// Components that render their own `h2` from `title` and `id` props. The
// heading is not in the MDX tree, so it is added to the table of contents here.
const sectionComponents = ['TroubleshootingStart', 'TroubleshootingTiles', 'StillStuck']
function jsxStringAttribute(node, name) {
let attribute = node.attributes?.find((a) => a.name === name)
return typeof attribute?.value === 'string' ? attribute.value : undefined
}
function getSections(node) { function getSections(node) {
let sections = [] let sections = []
for (let child of node.children ?? []) { for (let child of node.children ?? []) {
if (child.type === 'element' && ['h2', 'h3', 'h4', 'h5', 'h6'].includes(child.tagName)) { if (child.type === 'mdxJsxFlowElement' && sectionComponents.includes(child.name)) {
let title = jsxStringAttribute(child, 'title')
let id = jsxStringAttribute(child, 'id')
if (title && id) {
sections.push(`{
title: ${JSON.stringify(title)},
id: ${JSON.stringify(id)},
tagName: "h2"
}`)
}
} else if (child.type === 'element' && ['h2', 'h3', 'h4', 'h5', 'h6'].includes(child.tagName)) {
sections.push(`{ sections.push(`{
title: ${JSON.stringify(toString(child))}, title: ${JSON.stringify(toString(child))},
id: ${JSON.stringify(child.properties.id)}, id: ${JSON.stringify(child.properties.id)},
src/components/StillStuck.jsx
+85 -28
View File
@@ -1,48 +1,105 @@
import { Fragment } from 'react' import { Fragment } from 'react'
import Link from 'next/link'
import { Button } from '@/components/Button' import { Button } from '@/components/Button'
/** /**
* "Still stuck?" call-to-action banner for the bottom of the Troubleshooting * "Still stuck?" call-to-action banner for the bottom of the Troubleshooting
* hub. Renders a short prompt and a row of action buttons. * hub. Renders a centered title, a row of action buttons with an optional note
* under each, and an optional row of secondary links.
* *
* @param {string} [title='Still stuck?'] * @param {string} [title='Still stuck?']
* @param {string} description * @param {string} [id] - Optional id for the title anchor (listed in "On this page")
* @param {Array<{label: string, href: string, primary?: boolean}>} actions * @param {string} [description]
* @param {Array<{label: string, href: string, primary?: boolean, note?: string}>} actions
* @param {string} [separator] - Optional word rendered between buttons (e.g. "or"), * @param {string} [separator] - Optional word rendered between buttons (e.g. "or"),
* so two equally-weighted actions don't read as a recommended-vs-secondary pair. * so two equally-weighted actions don't read as a recommended-vs-secondary pair.
* @param {string} [linksLabel] - Lead-in text, on its own line above the secondary links
* @param {Array<{label: string, href: string}>} [links] - Secondary text links
*/ */
export function StillStuck({ export function StillStuck({
title = 'Still stuck?', title = 'Still stuck?',
id,
description, description,
actions = [], actions = [],
separator, separator,
linksLabel,
links = [],
}) { }) {
// `not-prose` on the card would also drop the prose layout (left margin and
// max width), so the outer div keeps it and matches TroubleshootingTiles.
return ( return (
<div className="not-prose my-12 rounded-2xl bg-zinc-50 p-6 ring-1 ring-inset ring-zinc-900/7.5 dark:bg-white/2.5 dark:ring-white/10"> <div className="my-12 xl:max-w-none">
<h2 className="text-xl font-semibold text-zinc-900 dark:text-white"> <div className="not-prose rounded-2xl bg-zinc-50 px-4 py-6 text-center ring-1 ring-inset ring-zinc-900/7.5 dark:bg-white/2.5 dark:ring-white/10">
{title} <h2
</h2> id={id}
{description && ( className="scroll-mt-24 text-xl font-semibold text-zinc-900 dark:text-white"
<p className="mt-1 max-w-2xl text-sm text-zinc-600 dark:text-zinc-400"> >
{description} {title}
</p> </h2>
)} {description && (
<div className="mt-5 flex flex-wrap items-center gap-3"> <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
{actions.map((action, i) => ( {description}
<Fragment key={action.href}> </p>
{i > 0 && separator && ( )}
<span className="text-sm text-zinc-500 dark:text-zinc-400"> {/* Stacked in reading order on phones. From `sm` up, a two-row grid puts
{separator} each note under its button and keeps the separator level with the
</span> buttons, not the notes. */}
)} <div
<Button className="mt-5 flex flex-col items-center gap-2 sm:grid sm:items-start sm:justify-center sm:gap-x-4 sm:[grid-template-columns:var(--cols)]"
href={action.href} style={{
variant={action.primary ? 'primary' : 'secondary'} '--cols': actions.map(() => 'minmax(0, 16rem)').join(' auto '),
> }}
{action.label} >
</Button> {actions.map((action, i) => (
</Fragment> <Fragment key={action.href}>
))} {i > 0 && separator && (
<span
className="text-sm text-zinc-500 sm:row-start-1 sm:self-center sm:[grid-column:var(--col)] dark:text-zinc-400"
style={{ '--col': 2 * i }}
>
{separator}
</span>
)}
<div
className="sm:row-start-1 sm:[grid-column:var(--col)]"
style={{ '--col': 2 * i + 1 }}
>
<Button
href={action.href}
variant={action.primary ? 'primary' : 'secondary'}
>
{action.label}
</Button>
</div>
{action.note && (
<p
className="text-xs text-zinc-500 sm:row-start-2 sm:[grid-column:var(--col)] dark:text-zinc-400"
style={{ '--col': 2 * i + 1 }}
>
{action.note}
</p>
)}
</Fragment>
))}
</div>
{links.length > 0 && (
<div className="mt-5 text-sm text-zinc-600 dark:text-zinc-400">
{linksLabel && <p>{linksLabel}</p>}
<p className={linksLabel ? 'mt-1' : undefined}>
{links.map((link, i) => (
<Fragment key={link.href}>
{i > 0 && <span aria-hidden="true"> · </span>}
<Link
href={link.href}
className="font-medium text-zinc-900 underline decoration-[#F28C28]/40 underline-offset-2 hover:decoration-[#F28C28] dark:text-white"
>
{link.label}
</Link>
</Fragment>
))}
</p>
</div>
)}
</div> </div>
</div> </div>
) )
src/pages/help/netbird-support.mdx
+2 -2
View File
@@ -1,7 +1,7 @@
import { SupportBanner } from "@/components/SupportBanner" import { SupportBanner } from "@/components/SupportBanner"
export const description = export const description =
"NetBird Support for (paying) Cloud customers and users, and commercial-license self-hosted deployments: reach the team with a pre-filled report." "NetBird Support, mainly for paying Cloud customers and commercial-license self-hosted deployments: reach the team with a pre-filled report."
export const reportTemplate = `NetBird issue report export const reportTemplate = `NetBird issue report
===================== =====================
@@ -39,7 +39,7 @@ export const supportMailto = `mailto:support@netbird.io?subject=${encodeURICompo
<SupportBanner <SupportBanner
tone="support" tone="support"
badge="Cloud & commercial" badge="Cloud & commercial"
description="Reserved for (paying) Cloud customers and users, and self-hosted deployments on a commercial license. Use it for the Cloud dashboard, the managed control plane, billing, your subscription, or commercial self-hosted support. Open source self-hosted and general client questions belong in Community Support." description="Mainly for paying NetBird Cloud customers and self-hosted deployments on a commercial license. Use it for the Cloud dashboard, the managed control plane, billing, your subscription, or commercial self-hosted support. Open source self-hosted and general client questions belong in Community Support."
links={[ links={[
{ label: "Open a pre-filled support email", href: supportMailto }, { label: "Open a pre-filled support email", href: supportMailto },
{ label: "Attach a debug bundle", href: "/help/troubleshooting-client#debug-bundle" }, { label: "Attach a debug bundle", href: "/help/troubleshooting-client#debug-bundle" },
src/pages/help/report-bug-issues.mdx
+1 -1
View File
@@ -19,7 +19,7 @@ NetBird offers two ways to get help, depending on what you are running. Pick the
{ {
href: "/help/netbird-support", href: "/help/netbird-support",
name: "NetBird Support", name: "NetBird Support",
description: "For (paying) Cloud customers and users, and commercial-license self-hosted deployments: the dashboard, control plane, billing, and subscriptions.", description: "Mainly for paying NetBird Cloud customers and commercial-license self-hosted deployments: the dashboard, control plane, billing, and subscriptions.",
}, },
]} ]}
/> />
src/pages/help/troubleshooting-account-access.mdx
+26 -2
View File
@@ -1,11 +1,13 @@
import {Note} from "@/components/mdx"; import {Note} from "@/components/mdx";
export const description = "Why NetBird shows you a Waiting for Approval screen, or adds you to an account you don't recognize, and how to resolve it safely." export const description = "Why NetBird shows you a Waiting for Approval screen, adds you to an account you don't recognize, or gives a teammate an account of their own, and how to resolve it safely."
# Pending approval and account invitations # Pending approval and account invitations
Signed in to NetBird and landed on a **Waiting for Approval** screen, or in a NetBird account you don't recognize? This usually is not a bug. It almost always means you were added to an existing organization automatically, and someone in that organization still has to approve you. Signed in to NetBird and landed on a **Waiting for Approval** screen, or in a NetBird account you don't recognize? This usually is not a bug. It almost always means you were added to an existing organization automatically, and someone in that organization still has to approve you.
The opposite also happens: a teammate signs in and gets a new, empty account of their own instead of joining yours. See [A teammate got their own account](#a-teammate-got-their-own-account).
## What the Waiting for Approval screen tells you ## What the Waiting for Approval screen tells you
After you sign in, the dashboard shows three steps: **Account Created**, **Waiting for Approval**, and **Join Account**. Your user exists, but the account requires new users to be approved before they can use it, so you are held at the second step until someone approves you. After you sign in, the dashboard shows three steps: **Account Created**, **Waiting for Approval**, and **Join Account**. Your user exists, but the account requires new users to be approved before they can use it, so you are held at the second step until someone approves you.
@@ -23,7 +25,7 @@ The screen has two buttons:
NetBird can add people to an account without a manual, one-by-one invite: NetBird can add people to an account without a manual, one-by-one invite:
- **Indirect (domain) invites.** If an account has verified your email domain, new sign-ups with that domain join it automatically. See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites). - **Domain matching.** On NetBird Cloud, new sign-ups join an existing account automatically when their email domain belongs to it: either the private domain the account signed up with, or another domain the account has verified as a [sign-in domain](/manage/team/sign-in-domains). See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites).
- **Identity provider sync.** If your organization connects NetBird to its identity provider, being added to a synced group in the IdP provisions your user in NetBird. See [Provision users and groups from your identity provider](/manage/team/idp-sync). - **Identity provider sync.** If your organization connects NetBird to its identity provider, being added to a synced group in the IdP provisions your user in NetBird. See [Provision users and groups from your identity provider](/manage/team/idp-sync).
- **Approval is required.** When an account turns on [user approval](/manage/team/approve-users#require-user-approval), new users stay blocked until an admin approves them. That block is the Waiting for Approval screen you see. - **Approval is required.** When an account turns on [user approval](/manage/team/approve-users#require-user-approval), new users stay blocked until an admin approves them. That block is the Waiting for Approval screen you see.
@@ -38,6 +40,28 @@ NetBird can add people to an account without a manual, one-by-one invite:
On self-hosted NetBird, the Waiting for Approval screen needs dashboard v2.93.0 or later, and the owner's address on it needs management v0.80.0 or later. Older dashboards show a **User Approval Pending** error page with only a **Sign Out** button instead: the steps above still apply, but after you are approved, sign out and sign in again. On self-hosted NetBird, the Waiting for Approval screen needs dashboard v2.93.0 or later, and the owner's address on it needs management v0.80.0 or later. Older dashboards show a **User Approval Pending** error page with only a **Sign Out** button instead: the steps above still apply, but after you are approved, sign out and sign in again.
</Note> </Note>
## A teammate got their own account
A teammate signs in to NetBird Cloud and lands in a new, empty account, with none of your peers, users, or policies. NetBird did not match their email domain to your account, so it created a separate one for them. One of these is usually the reason:
- **They use another of your business's domains.** Only the domain your account signed up with matches from the start. A country domain such as `company.co.uk`, a subsidiary, or a second brand matches only after an Owner or Admin adds and verifies it as a [sign-in domain](/manage/team/sign-in-domains).
- **They signed in with a personal address**, such as a Gmail account. Public email domains never match an account. Ask them to sign in with their work address instead. You can't [invite them directly](/manage/team/add-users-to-your-network#direct-user-invites) now that they have their own account, so if they need to keep the personal address, contact [NetBird Support](/help/netbird-support).
- **Your domain was not classified as private.** NetBird only groups sign-ups by domain when it classifies the domain as private. If it is unsure, it plays safe and does not group them. [NetBird Support](/help/netbird-support) can correct the classification. See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites).
To fix it for the next person, an Owner or Admin adds and verifies the domain under **Settings → Authentication → Sign-in Domains**, or invites the user directly. Do this before onboarding a team on another domain, not after.
The **Sign-in Domains** section only appears once your account's own domain is classified as private. If you don't see it, invite the user directly or contact [NetBird Support](/help/netbird-support).
To confirm the cause, ask your teammate which email address they signed in with, and check its domain against the Sign-in Domains list.
Verifying a domain does not move a teammate who already has an account of their own: it only changes where new sign-ins land. For a teammate already in a separate account, contact [NetBird Support](/help/netbird-support).
If your account requires user approval, a teammate who joins through domain matching is held for approval. That is the [Waiting for Approval](#what-the-waiting-for-approval-screen-tells-you) screen above, and an admin approves them as described in [What to do](#what-to-do).
<Note>
On self-hosted NetBird, domain matching and sign-in domains do not apply: by default, every user joins the same account.
</Note>
<Note> <Note>
Still unsure who owns the account, or think you were added to the wrong one? Reach out through [NetBird Support](/help/netbird-support) and the team can help confirm the account and its owner. Still unsure who owns the account, or think you were added to the wrong one? Reach out through [NetBird Support](/help/netbird-support) and the team can help confirm the account and its owner.
</Note> </Note>
src/pages/help/troubleshooting.mdx
+102 -43
View File
@@ -2,43 +2,90 @@ import { TroubleshootingTiles } from "@/components/TroubleshootingTiles"
import { StillStuck } from "@/components/StillStuck" import { StillStuck } from "@/components/StillStuck"
export const description = export const description =
"Start here to troubleshoot NetBird. Find your issue by area and jump straight to the relevant guide." "Start here to troubleshoot NetBird. See the common issues, or browse by area."
# Troubleshooting # Troubleshooting
Something not working as expected? Pick the area closest to your problem and jump to the Something not working as expected? Check the common issues below, or browse by area.
guide and section that covers it. Each section links to troubleshooting docs that live
next to the feature they cover, so nothing here is a copy. ## Common issues
The problems support sees most often.
<div className="xl:max-w-none [&_table]:table-fixed [&_th]:w-1/2 [&_th:last-child]:pl-8 [&_td:last-child]:pl-8">
| Symptom | Start here |
|---|---|
| The dashboard shows **Waiting for Approval** after you sign in | [Pending approval and account invitations](/help/troubleshooting-account-access) |
| The client keeps asking you to log in again, or a peer shows `Login required` | [Peer session expiration](/manage/settings/enforce-periodic-user-authentication) |
| A peer shows `Relayed` instead of `P2P` | [Troubleshooting relayed connections](/help/troubleshooting-relayed-connections) |
| The tunnel works but is slow, or takes long to connect | [Troubleshooting performance](/help/troubleshooting-performance) |
| A service behind a routing peer is unreachable, or a new resource never shows up | [Troubleshooting resource connectivity](/help/troubleshooting-resource-connectivity) |
| A network or host firewall blocks NetBird, or traffic stops at a security product such as a SASE or SSL-inspection service | [Ports & firewalls](/about-netbird/ports-and-firewalls) <br /> On the peer itself: [Symptoms of host-based firewall issues](/about-netbird/ports-and-firewalls#symptoms-of-host-based-firewall-issues) |
| Names do not resolve, or DNS stops working after NetBird disconnects | [DNS troubleshooting](/manage/dns/troubleshooting) |
| A NetBird Reverse Proxy service returns `502`, times out, or its certificate is never issued | [Reverse proxy troubleshooting](/manage/reverse-proxy/troubleshooting) <br /> Certificate: [Certificate is not issued after verification](/manage/reverse-proxy/custom-domains#certificate-is-not-issued-after-verification) |
</div>
<TroubleshootingTiles <TroubleshootingTiles
title="Find your issue by area" title="Find your issue by area"
id="find-your-issue-by-area" id="find-your-issue-by-area"
description="Pick the surface you are working with. Links open the existing troubleshooting docs in place." description="Pick the part of NetBird you are working with, then the problem closest to yours."
items={[ items={[
{ {
title: "NetBird Client", title: "NetBird Client",
href: "/help/troubleshooting-client", href: "/help/troubleshooting-client",
icon: "laptop", icon: "laptop",
description: description:
"Desktop, CLI, and mobile client problems on a peer machine.", "Desktop, CLI, and mobile client problems on a peer machine: status, logs, login, and platform quirks.",
chips: [ chips: [
{ label: "Connection issues", href: "/help/troubleshooting-client#debugging-ice-connections" }, { label: "Client status", href: "/help/troubleshooting-client#net-bird-client-status" },
{ label: "Debug bundle", href: "/help/troubleshooting-client#debug-bundle" },
{ label: "Debug logs", href: "/help/troubleshooting-client#enabling-debug-logs-on-the-client" },
{ label: "Login & SSO", href: "/help/troubleshooting-client#client-login-failures" }, { label: "Login & SSO", href: "/help/troubleshooting-client#client-login-failures" },
{ label: "DNS resolution", href: "/manage/dns/troubleshooting" }, { label: "Windows SSO port 53000", href: "/help/troubleshooting-client/windows#sso-login-fails-to-bind-tcp-53000" },
{ label: "Routes & exit nodes", href: "/help/troubleshooting-client#debugging-access-to-network-resources" }, { label: "Stuck at Connecting", href: "/help/troubleshooting-client#debugging-ice-connections" },
{ label: "Host firewall fallback", href: "/help/troubleshooting-client#when-the-client-cannot-manage-firewall-rules" },
{ label: "Linux", href: "/help/troubleshooting-client/linux" },
{ label: "Windows", href: "/help/troubleshooting-client/windows" },
{ label: "macOS", href: "/help/troubleshooting-client/macos" },
{ label: "Android", href: "/help/troubleshooting-client/android" },
{ label: "iOS", href: "/help/troubleshooting-client/ios" },
], ],
}, },
{ {
title: "Self-hosted", // No dedicated troubleshooting page, so the title is plain text.
href: "/selfhosted/troubleshooting", title: "Connectivity & networking",
icon: "server", icon: "firewall",
description: description:
"Your own Management, Signal, Relay, and Dashboard services.", "Peers that relay, never connect, or can't reach resources, plus DNS and speed, whether you use NetBird Cloud or self-host.",
chips: [ chips: [
{ label: "Management service", href: "/selfhosted/troubleshooting/connectivity#management-service-unreachable" }, { label: "Relayed connections", href: "/help/troubleshooting-relayed-connections" },
{ label: "Signal service", href: "/about-netbird/how-netbird-works#signal-service" }, { label: "Control plane unreachable", href: "/help/troubleshooting-relayed-connections#step-2-is-the-control-plane-reachable" },
{ label: "Relay", href: "/selfhosted/troubleshooting/connectivity#debugging-relay-connections" }, { label: "Resource connectivity", href: "/help/troubleshooting-resource-connectivity" },
{ label: "Dashboard", href: "/selfhosted/troubleshooting/dashboard" }, { label: "Routing peer forwarding", href: "/help/troubleshooting-resource-connectivity#step-3-does-the-peer-forward-it" },
{ label: "Routing peer checks", href: "/manage/networks/how-routing-peers-work#observability-and-troubleshooting" },
{ label: "Performance", href: "/help/troubleshooting-performance" },
{ label: "Reconnect delays", href: "/help/troubleshooting-performance#startup-and-reconnect-delays" },
{ label: "MTU", href: "/help/troubleshooting-performance#rule-out-packet-size-mtu" },
{ label: "DNS", href: "/manage/dns/troubleshooting" },
{ label: "Ports & firewalls", href: "/about-netbird/ports-and-firewalls" },
{ label: "Corporate firewalls & SASE", href: "/about-netbird/ports-and-firewalls#corporate-firewalls" },
{ label: "Other VPNs on Linux", href: "/client/environment-variables#networking-and-routing" },
],
},
{
// No dedicated troubleshooting page, so the title is plain text;
// chips point to the sections that diagnose policy decisions.
title: "Access control",
icon: "shield",
description:
"Traffic allowed or denied unexpectedly by a policy or posture check.",
chips: [
{ label: "Check the matching policy", href: "/help/troubleshooting-resource-connectivity#step-2-is-there-a-route-and-a-matching-policy" },
{ label: "Trace firewall rules", href: "/help/troubleshooting-client#tracing-firewall-rules" },
{ label: "When posture checks run", href: "/manage/access-control/posture-checks#when-posture-checks-are-evaluated" },
{ label: "Posture check limits", href: "/manage/access-control/posture-checks#known-limitations" },
], ],
}, },
{ {
@@ -47,41 +94,47 @@ next to the feature they cover, so nothing here is a copy.
title: "Cloud & identity", title: "Cloud & identity",
icon: "cloud", icon: "cloud",
description: description:
"SSO and user provisioning (Cloud and self-hosted), account approvals, and Cloud plans and quotas.", "Approvals, landing in the right account, session expiry, SSO and provisioning, MSP tenants, and NetBird Cloud plans.",
chips: [ chips: [
{ label: "Pending approval", href: "/help/troubleshooting-account-access" }, { label: "Pending approval", href: "/help/troubleshooting-account-access" },
{ label: "IdP & SSO setup", href: "/manage/team/single-sign-on" }, { label: "Teammate got their own account", href: "/help/troubleshooting-account-access#a-teammate-got-their-own-account" },
{ label: "User provisioning", href: "/manage/team/idp-sync" }, { label: "Sign-in domains", href: "/manage/team/sign-in-domains" },
{ label: "Plan limits & quotas", href: "/manage/settings/plans-and-billing" }, { label: "Session expiration", href: "/manage/settings/enforce-periodic-user-authentication" },
{ label: "SSO setup guides", href: "/manage/team/single-sign-on" },
{ label: "User provisioning setup", href: "/manage/team/idp-sync" },
{ label: "MSP tenants", href: "/manage/for-partners/msp-portal#delayed-tenant-domain-verification" },
{ label: "Plans & billing", href: "/manage/settings/plans-and-billing" },
], ],
}, },
{ {
title: "Connectivity & networking", title: "Reverse Proxy",
href: "/help/troubleshooting-relayed-connections", href: "/manage/reverse-proxy/troubleshooting",
icon: "firewall", icon: "globe",
description: description:
"Cross-cutting network issues regardless of how you deploy.", "Services you expose with the NetBird Reverse Proxy: errors, timeouts, and custom domains.",
chips: [ chips: [
{ label: "Relayed connections", href: "/help/troubleshooting-relayed-connections" }, { label: "Quick checklist", href: "/manage/reverse-proxy/troubleshooting#quick-diagnostics-checklist" },
{ label: "Resource connectivity", href: "/help/troubleshooting-resource-connectivity" }, { label: "502 to the routing peer's own IP", href: "/manage/reverse-proxy/troubleshooting#issue-1-502-errors-when-routing-peer-forwards-to-its-own-ip" },
{ label: "Performance", href: "/help/troubleshooting-performance" }, { label: "Service on localhost", href: "/manage/reverse-proxy/troubleshooting#issue-2-service-bound-to-localhost-is-unreachable" },
{ label: "Reverse proxy", href: "/manage/reverse-proxy/troubleshooting" }, { label: "TCP service gets no response", href: "/manage/reverse-proxy/troubleshooting#issue-4-tcp-service-is-active-but-connections-get-no-response" },
{ label: "NAT & firewall ports", href: "/about-netbird/ports-and-firewalls" }, { label: "Domain Pending Verification", href: "/manage/reverse-proxy/custom-domains#domain-shows-as-pending-verification" },
{ label: "Corporate firewalls", href: "/about-netbird/ports-and-firewalls#corporate-firewalls" }, { label: "Certificate not issued", href: "/manage/reverse-proxy/custom-domains#certificate-is-not-issued-after-verification" },
{ label: "DNS", href: "/manage/dns/troubleshooting" },
{ label: "Network routes", href: "/manage/network-routes" },
], ],
}, },
{ {
title: "Access control", title: "Self-hosted",
href: "/manage/access-control", href: "/selfhosted/troubleshooting",
icon: "shield", icon: "server",
description: description:
"Traffic being allowed or denied unexpectedly.", "Your own NetBird server: installation, identity, dashboard, certificates, connectivity, and database.",
chips: [ chips: [
{ label: "Policies", href: "/manage/access-control" }, { label: "Installation", href: "/selfhosted/troubleshooting/installation" },
{ label: "Posture checks", href: "/manage/access-control/posture-checks" }, { label: "Embedded IdP", href: "/selfhosted/troubleshooting/identity-provider" },
{ label: "Groups", href: "/manage/access-control#understanding-groups" }, { label: "Dashboard", href: "/selfhosted/troubleshooting/dashboard" },
{ label: "Certificates", href: "/selfhosted/troubleshooting/certificates" },
{ label: "Connectivity", href: "/selfhosted/troubleshooting/connectivity" },
{ label: "Management unreachable", href: "/selfhosted/troubleshooting/connectivity#management-service-unreachable" },
{ label: "Database", href: "/selfhosted/troubleshooting/database" },
], ],
}, },
]} ]}
@@ -89,10 +142,16 @@ next to the feature they cover, so nothing here is a copy.
<StillStuck <StillStuck
title="Still stuck?" title="Still stuck?"
description="Bring your debug bundle. The community and the team can help from there." id="still-stuck"
separator="or" separator="or"
actions={[ actions={[
{ label: "Contact our Community", href: "/help/community-support", primary: true }, { label: "Contact our Community", href: "/help/community-support", primary: true, note: "Free for everyone." },
{ label: "Contact NetBird Support", href: "/help/netbird-support", primary: true }, { label: "Contact NetBird Support", href: "/help/netbird-support", primary: true, note: "Mainly for paying NetBird Cloud customers and commercial-license deployments." },
]}
linksLabel="Preparing a report? Include your NetBird version (netbird version) and steps to reproduce. For problems on a peer, add a debug bundle."
links={[
{ label: "Debug bundle", href: "/help/troubleshooting-client#debug-bundle" },
{ label: "Record a HAR file", href: "/help/recording-a-har-file" },
{ label: "Support matrix", href: "/help/support-matrix" },
]} ]}
/> />
src/pages/selfhosted/troubleshooting.mdx
+1
View File
@@ -41,6 +41,7 @@ This page helps with issues when self-hosting NetBird. Collect the diagnostics b
<TroubleshootingStart <TroubleshootingStart
eyebrow="Start here" eyebrow="Start here"
title="Collect diagnostics first" title="Collect diagnostics first"
id="collect-diagnostics-first"
description="Almost every self-hosted issue is faster to resolve with service status and logs in hand. Grab these before you go deeper." description="Almost every self-hosted issue is faster to resolve with service status and logs in hand. Grab these before you go deeper."
steps={[ steps={[
{ label: "1. Check services", title: "Service status", command: "docker compose ps", hint: "Are netbird-server and dashboard Up, plus traefik if you chose the built-in Traefik? Installs from before v0.65.0 run separate management, signal, and relay services instead." }, { label: "1. Check services", title: "Service status", command: "docker compose ps", hint: "Are netbird-server and dashboard Up, plus traefik if you chose the built-in Traefik? Installs from before v0.65.0 run separate management, signal, and relay services instead." },