Troubleshooting Development Issues

Issues with Installing the Recommended Prerequisites

We regularly develop on the latest or most popular operating systems like macOS 10.15 or later, Ubuntu 20.04 or later, and Windows 10 or later (with WSL2).

It is recommended to research your specific issue on resources such as Google, Stack Overflow, and Stack Exchange. There is a good chance that someone has faced the same issue and there is already an answer to your specific query.

If you are on a different OS or are still facing issues, see getting help.

Performance and Stability Issues on WSL2 Linux Distro

If you are working on a WSL2 Linux Distro, you might get performance and stability issues by running this project in a folder which is shared between Windows and WSL2 (e.g. /mnt/c/Users/).

Therefore we recommend to clone this repo into a folder which is mainly used by your WSL2 Linux Distro and not directly shared with Windows (e.g. ~/PROJECTS/).

See this GitHub Issue for further information about this problem.

Troubleshooting port issues on Gitpod

Sometimes the service on port 8000 doesn’t go live. This is common when you are restarting an inactive workspace.

If the service is not coming up on port 8000, you can troubleshoot using these steps:

Start the server: Run the below command in one terminal window from the root project directory (/workspace/freeCodeCamp).
Terminal window
```
pnpm run develop:server
```
Start the client: In another terminal window, run the below command from the client directory (/workspace/freeCodeCamp/client).
Terminal window
```
pnpm run develop -- -H '0.0.0.0'
```

This should make port 8000 available. Be mindful of how the URLs & Ports work within a Gitpod workspace.

Issues with Missing UI, Fonts, Language Strings, or Build Errors

When you build the client, Gatsby will cache the fonts, language strings, and UI. If one of them isn’t cached, run the following:

pnpm run clean

pnpm install

pnpm run seed

pnpm run develop

Use the shorter handy command that does the above steps:

pnpm run clean-and-develop

If you continue to face issues with the build, cleaning up the workspace is recommended.

Use git clean in interactive mode:

git clean -ifdX

How to clean git untracked files (screenshot)

If you can’t sign in, and instead you see a banner with an error message saying that the error will be reported to freeCodeCamp, please double-check that your local port 3000 is not in use by a different program.

From Terminal:

netstat -a | grep "3000"

Check the output:

tcp4    0   0    0.0.0.0:3000           DESKTOP      LISTEN

Issues Signing Out while Navigating

While in development, your session is stored as cookies. Clearing them will sign you out of your development account.

Running pnpm run seed:certified-user will log you out, too. It will overwrite the development user in your local database.

Issue Getting 404 when Navigating Profile Page

When you try to navigate to http://localhost:8000/developmentuser to view the profile page, Gatsby takes over serving the client-side pages and hence you will get a 404 page for the user profile when working.

There is a “Preview Custom 404 Page” button, click it to see the profile.

Issues Installing Dependencies

If you get errors while installing the dependencies, please make sure that you are not in a restricted network or your firewall settings do not prevent you from accessing resources.

Working With Other Languages

To see how the client renders in another language go to How to Work on Localized Client Webapp.

Getting Help

If you are stuck and need help, feel free to ask questions in the ‘Contributors’ category on our forum or the contributors chat room.

There might be an error in the console of your browser or in Bash / Terminal / Command Line that will help identify the problem. Provide this error message in your problem description so others can more easily identify the issue and help you find a resolution.