# Common issues and solutions

## Common issues and solutions

Use this page when you are starting Conduit, signing in, waiting for authentication,
or opening a route that depends on your authentication state.

| If you need to… | Go to |
|---|---|
| Start the application and reach Home | [Set up the application and reach Home](#set-up-the-application-and-reach-home) |
| Sign in or create an account | [Sign in or create an account](#sign-in-or-create-an-account) |
| Interpret `Loading...` or `Connecting...` | [Recognize loading and unavailable authentication](#recognize-loading-and-unavailable-authentication) |
| Understand why a route does not open | [Handle guarded routes and settings access](#handle-guarded-routes-and-settings-access) |
| Work through an authentication or setup problem | [Troubleshoot authentication, setup, and settings problems](#troubleshoot-authentication-setup-and-settings-problems) |

## Before you start

Have the following ready before you begin:

| What you need | Why it matters |
|---|---|
| Bun | Conduit requires Bun to run the setup and start commands. |
| The setup sequence | Run `bun run setup`, then `bun run start`. |
| The correct authentication state | Settings requires authentication. Login and Register are for unauthenticated access. |

Keep the account details you need for the Login or Register form ready before you start.
On Settings, enter a new password only when you want to change it.

## Set up the application and reach Home

Home is the starting surface for the article feeds. The application loads it at `/`, where
you can use **Your Feed** when authenticated or **Global Feed** otherwise.

**Prerequisites**

- Have Bun installed.
- Have the project available locally.

**Steps**

1. In a terminal, enter the command `bun run setup`.
2. Run `bun run start`.
3. Open `/`.
4. Select **Global Feed** to view the global feed.
5. Select **Your Feed** when you are authenticated and want the following feed.

**Result:** Home opens at `/` with the feed choices available according to your
authentication state. You can now continue to Login or Register.

## Sign in or create an account

Login authenticates an existing account with **Email** and **Password**. Register creates
an account with **Username**, **Email**, and **Password**.
Login requires **Email** and **Password**. Register requires **Username**, **Email**, and
**Password**.

**Prerequisites**

- Be unauthenticated.
- Have an account for Login, or be ready to create one with Register.

**Steps**

1. Choose the route that matches what you need:

   | If you need to… | Open |
   |---|---|
   | Access an existing account | `/login` |
   | Create an account | `/register` |

2. Complete the fields for the route:

   | Route | Fields |
   |---|---|
   | `/login` | **Email** and **Password** |
   | `/register` | **Username**, **Email**, and **Password** |

3. Choose the account action that matches your route:

   | If you need to… | Select |
   |---|---|
   | Submit Login | **Sign in** |
   | Submit Register | **Sign up** |
   | Move from Login to Register | **Need an account?** |
   | Move from Register to Login | **Have an account?** |

**Result:** A successful sign-in or registration navigates to `/`. Continue to [Recognize
loading and unavailable authentication](#recognize-loading-and-unavailable-authentication).

## Recognize loading and unavailable authentication

The header communicates whether Conduit is still checking authentication or is retrying
after an unavailable authentication service.

| What you see | Meaning in the application flow |
|---|---|
| `Loading...` | Authentication is loading. |
| `Connecting...` | Authentication is unavailable and the application is retrying. |
| `Auth unavailable - retrying automatically` | The title on the retry status. |

The authentication service treats a 4XX response while loading `/user` as invalid
authentication and purges it. A 5XX or network error keeps the token and enters the
unavailable state. Retry delays are 2, 4, 8, and then 16 seconds, with 16 seconds as the
cap.

## Handle guarded routes and settings access

Settings is an authenticated route. Login and Register are routes for unauthenticated
readers, so the application applies the opposite route condition to them.

**Prerequisites**

- Know whether you are currently authenticated.
- Open `/settings` only when you are authenticated.

**Steps**

1. Open `/settings`.
2. Choose the route that matches your authentication state:

   | If you are… | Do this |
   |---|---|
   | Unauthenticated | Open `/login` and complete the sign-in procedure. |
   | Authenticated and managing account details | Select **Settings**. |

**Result:** Authenticated access can continue to Settings; unauthenticated access to
Settings is directed to `/login`.

## Troubleshoot authentication, setup, and settings problems

Use the message on screen to choose the next action. Authentication and Settings display
API error values in the error list.

**Prerequisites**

- Have the Login, Register, or Settings screen open.
- Have the message you need to resolve visible on screen.

**Steps**

1. Read the message shown on screen.
2. Choose the response that matches the message:

   | If you see… | Meaning | Do this |
   |---|---|---|
   | `Loading...` | The application has not finished checking authentication. | Wait until the authentication state resolves. |
   | `Connecting...` | The authentication check is retrying. | Allow the retry state to continue. |
   | `Auth unavailable - retrying automatically` | The header reports unavailable authentication. | Check the authentication state again after the retry. |
   | An API error value | The submitted request returned an error value. | Review the displayed value. Edit the submitted fields to correct the displayed problem. Select **Sign in**, **Sign up**, or **Update Settings** to submit the form again. |

The application retries unavailable authentication at 2, 4, 8, and 16-second intervals,
then continues at the 16-second cap.

**Result:** The message remains available while the application is loading or retrying, or
the form is ready for another submission after you correct the displayed problem.

## Continue with the related task

Continue with the page that owns the next action:

- [Sign in](doc:sign-in) for the Login procedure.
- [Create an account](doc:create-an-account) for registration.
- [Authentication and loading messages](doc:authentication-and-loading-messages) for the message reference.
- [Loading and unavailable states](doc:loading-and-unavailable-states) for loading-state handling.
- [Update settings](doc:update-settings) for changing account details.
- [Sign out](doc:sign-out) for ending the authenticated session.
- [General error messages](doc:general-error-messages) for application error messages.
- [FAQ](doc:faq) for broader questions.