# Troubleshoot the Enterprise Portal

:::note Alpha Feature
Features described on this page are in alpha and subject to change. For access, contact your Replicated account representative.
:::

This topic provides solutions for common issues when setting up and using the new Enterprise Portal.

## Repository not showing in dropdown

If a repository doesn't appear when linking content or Terraform repos, the Replicated GitHub App likely doesn't have access to it. Update permissions in GitHub: Settings > Integrations > Applications > Replicated > Configure > Repository access. After updating, return to the Content tab and the repository should appear.

## Changes not appearing

GitHub integration automatically syncs on push. If changes aren't appearing:

- Check the sync status in the Content tab
- Trigger manual sync from the Content tab (click "Sync")

API manual sync (see [Connect a Git Repo](/vendor/enterprise-portal-v2-connect-repo) for how to get your `REPO_ID`):

```
replicated api post /v3/app/<APP_ID>/enterprise-portal/content-repos/<REPO_ID>/sync
```

## Updated `main` but customers still see old content

The `main` branch is only the last-resort fallback. When a customer views a release, Enterprise Portal serves the highest version branch whose name is at or below that release version (nearest lower semver), and falls back to `main` only when no such branch exists. A stray version branch (for example, `v0.0.1`) sorts at or below almost every release, so it captures those releases and serves its own content, even after you update `main`.

- On the Content tab, check which branches are synced. If you are not maintaining version-specific docs, keep only `main` and delete stray version branches so every release falls back to `main`.
- If you are using versioned docs, update the version branch that actually serves the release, not just `main`.

See [Manage Content Versions](/vendor/enterprise-portal-v2-versioned-docs) for how version resolution works.

## Pages not showing in navigation

- Check `toc.yaml` includes the page
- Ensure file path matches `toc.yaml` reference
- Verify visibility rules (entitlements, channels)
- Check frontmatter `visible_when` conditions
- Confirm customer has required entitlements enabled

## Local preview "Page not found"

- Branch names with `/` (like `feature/foo` or `austin/initial-customization`) are treated as nested URL path segments in the preview. Use flat branch names (like `feature-foo`) to avoid this.
- The `main` branch is hidden from the version list when other branches exist. If you only have `main`, it shows as the sole version. If you have other branches, navigating to a URL with `/main/` in the path returns a 404.
- Uncommitted changes only appear on your currently checked-out branch. Other branches serve their last committed state.

## Local preview: "content path does not exist"

The preview command's example path is a placeholder. If you see `content path does not exist: /path/to/repo`, you ran the example literally. Replace `/path/to/repo` with the absolute path to your locally cloned content repo, for example `~/repos/acme-enterprise-portal-content`. See [Local preview](/vendor/enterprise-portal-v2-access#local-preview).

## Version branch not working

- Check branch exists: `git branch -r`
- Any branch other than `main` becomes a version
- For version gating to work, branch names must match release `version_label` values (see [Naming your branches](/vendor/enterprise-portal-v2-versioned-docs#naming-your-branches))

## Helm chart reference docs not generating

- Confirm the `name` in `toc.yaml` matches a chart name in the promoted release (not the release name, the Helm chart name from `Chart.yaml`)
- Reference docs generate asynchronously after promotion. Allow a few minutes
- If the chart hasn't changed since the last promotion (same `values.yaml` and `Chart.yaml`), regeneration is skipped
- Values annotated with `# @docs:skip` or `# @docs:internal` are intentionally excluded

## Terraform module docs not loading

- Verify the Terraform module repo is accessible by your GitHub App installation
- Check the `ref` (tag/branch) exists in the Terraform repo
- Confirm the module path is correct (subdirectory after `//`)
- Allow a few minutes for AI-generated content to process

## Terraform proxy registry not working

- Verify the GitHub App is installed and has access to the Terraform repo (**Enterprise Portal > Terraform**)
- Confirm the Terraform repo is linked (this is a separate repo from the content repo)
- Check the customer's license is active, not expired or archived
- Ensure `version_label` on the channel release matches the git tag (with `v` prefix: version `1.0.0` requires tag `v1.0.0`)
- Confirm `~/.terraformrc` has credentials for `proxy.replicated.com`
- Only `github` is supported as the provider suffix in the module source

## Security Center not showing

- Check the per-customer toggle: on the customer's **Enterprise Portal access** tab, **Enable Security Center for this customer** must be on
- If **Portal Version** is available, confirm that it is set to **Use new Enterprise Portal for this customer**
- Verify the Security page is included in your `toc.yaml`
- Confirm that the customer's license supports Helm or Embedded Cluster releases. Security reports are not available for KOTS or kURL releases
- Security data is generated from release scans. If no releases have been promoted or scans are incomplete, some security data is not available

## Customer not seeing new portal

- Confirm the customer's **Portal Version** is set to the new portal on their **Enterprise Portal access** tab
- Verify the Enterprise Portal site is deployed (check that the Content tab shows a linked repo and synced branches)
- If using a custom domain, confirm the CNAME record points your subdomain at `custom.enterpriseportal.app`, not the Classic domain (`get.replicated.com`). For how to add and verify a custom domain, see [Configure a Custom Domain](/vendor/enterprise-portal-v2-domains)

## Customer invitation not received

- Check the **Email History** on the customer's EP access tab for delivery status
- Verify the customer's email domain is not blocked by **Domain Restrictions** (if enabled)
- Check spam/junk folders. If using a custom email sender domain, confirm DKIM and Return-Path DNS records are verified
- If the customer has a pending invite and goes to the login page, they will be prompted to enter their invite code directly

## Self-service signup not working

- Confirm self-service sign-ups are enabled in **Enterprise Portal > Self-Service Sign-Ups**
- The signup URL is unique to your application. Verify the URL being shared is correct

## SAML login errors {#saml-login-errors}

The Enterprise Portal login page surfaces these errors directly to the customer user. The domain check runs before the invitation check, so a new user from a domain that is not allowed sees `domain_not_allowed` even when they also lack an invitation. Check the errors in the following order.

- `domain_not_allowed`: the user's email domain is absent from the customer's allowed domain list. Add the domain to the **Domain Restrictions** list on the customer's **Enterprise Portal access** tab, or have the user log in with an address on an allowed domain. This check applies only when the portal creates the account, so removing a domain from the list does not lock out users who were already provisioned from it
- `saml_invite_required`: the login started at the portal login page, and that email address has no pending invitation. Invite the user, or have them start the login from their identity provider instead, which provisions with no invitation. For the difference between the two flows, see [Just-in-time user provisioning](/vendor/enterprise-portal-v2-invite#jit-provisioning) in _Manage Customer Access_
- `saml_invalid_email`: the SAML assertion carried no email address, or one the portal could not use. Confirm that the identity provider releases an email attribute for the user
- `saml_auth_failed`: a general SAML failure. The portal returns this error both when it starts the login and when it processes the assertion, so it covers configuration problems on either side. Confirm that **SAML Authentication** is enabled for the customer in the Vendor Portal, and that the identity provider metadata URL and signing certificate in the customer's portal team settings are current

## Login footer showing Replicated branding

- Customize the login page footer by setting `loginFooterText` and `loginFooterLinks` in your `theme.yaml`
- On `*.enterpriseportal.app` domains (no custom domain), keeping a footer is recommended to avoid Google Safe Browsing flagging
- On custom domains, you can remove the footer entirely by omitting the fields or setting `loginFooterText` to an empty string