From 01f43dfd25da6d329b5ec4cc4eb9196f9e1a5ec3 Mon Sep 17 00:00:00 2001 From: Rohan Malhotra <139499925+rohanmalhotracodes@users.noreply.github.com> Date: Wed, 25 Feb 2026 21:34:46 +0530 Subject: [PATCH 1/4] docs: update Troubleshooting page with discussion-based fixes - Added note at top of page - Added troubleshooting entries from GitHub Discussions - Updated Table of Contents Fixes #207 --- Troubleshooting.md | 98 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/Troubleshooting.md b/Troubleshooting.md index f9de7e36..0112a36b 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -1,3 +1,10 @@ +> **Note:** This page includes solutions from GitHub Discussions that have a last-updated date before February 25, 2026. +> +> If you can't find your error here, try: +> 1. Searching for it on GitHub Discussions and reading the corresponding threads. +> 2. Searching for it on our issue tracker to see if there are related issues. +> 3. Searching for it on the Internet to see if others have encountered it and what they did to solve it. + ## General Here are some general troubleshooting tips for Oppia. The platform specific tips are [Linux](#linux), [Windows](#windows), and [Mac OS](#mac-os). @@ -26,6 +33,13 @@ Here are some general troubleshooting tips for Oppia. The platform specific tips - [`./portserver.socket is not listed in the .github/CODEOWNERS file`](#portserversocket-is-not-listed-in-the-githubcodeowners-file) - [Push fails due to connection timeout](#push-fails-due-to-connection-timeout) - [Exception: Error compiling proto files](#exception-error-compiling-proto-files) +- [Cron jobs: "Run now" returns 400](#cron-jobs-run-now-returns-400) +- [404 when opening `/learn/math`](#404-when-opening-learnmath) +- [Blank page or frontend not loading](#blank-page-or-frontend-not-loading) +- [404 when opening `/admin`](#404-when-opening-admin) +- [Unable to generate translation opportunities locally](#unable-to-generate-translation-opportunities-locally) +- [Webpack “Cannot resolve module ‘fs’” frontend error](#webpack-cannot-resolve-module-fs-frontend-error) +- [oppia-angular-build container exits during install/run](#oppia-angular-build-container-exits-during-installrun) - [Linux](#linux) - [OSError: \[Errno 2\] No such file or directory](#oserror-errno-2-no-such-file-or-directory) - [Pip: Cannot Import Name Main](#pip-cannot-import-name-main) @@ -57,7 +71,7 @@ Here are some general troubleshooting tips for Oppia. The platform specific tips - [If the above doesn't work](#if-the-above-doesnt-work) ### For Jio India Users -It seems the Jio network is blocking the domain `raw.githubusercontent.com` which is used by Github for storage of images in this wiki and some of the dependencies while installing Opia.. If you are using Jio, you can try changing the DNS address to 8.8.8.8 (Google DNS) or 1.1.1.1 (Cloudfare DNS) from settings. Original discussion [here](https://github.com/orgs/community/discussions/42655) +It seems the Jio network is blocking the domain `raw.githubusercontent.com` which is used by GitHub for storage of images in this wiki and some of the dependencies while installing Oppia.. If you are using Jio, you can try changing the DNS address to 8.8.8.8 (Google DNS) or 1.1.1.1 (Cloudfare DNS) from settings. Original discussion [here](https://github.com/orgs/community/discussions/42655) ### `[Errno 104] Connection reset by peer` If after running `python -m scripts.start` you get the following lines: @@ -310,6 +324,88 @@ Traceback (most recent call last) : Try searching for where protoc is installed (probably in `/opt/homebrew/bin/protoc`) and remove it and then re-run the command. +### Cron jobs: "Run now" returns 400 + +If clicking **Run now** for a cron job shows `Request failed with status: 400`, note that this interface may not be commonly used and might not work reliably. + +**Workaround:** manually trigger the cron job's attached endpoint while your dev server is running, and verify that it executed by checking the server logs (for example, by adding temporary print/log statements in the triggered methods). + +### 404 when opening `/learn/math` + +If opening `http://localhost:8181/learn/math` in your local dev server shows a **404 Page Not Found**, it's likely because Oppia does not yet have a valid classroom for that topic. In Oppia, learner content pages (like `/learn/math`) are only served when a corresponding classroom exists. + +**Solution:** +1. Assign the **admin role** from the admin UI roles tab. +2. Create a classroom that includes the math topic (via the admin activities or classroom admin page). +3. Once the classroom exists, `/learn/math` should load correctly. + +### Blank page or frontend not loading + +If the dev server starts successfully but the page appears blank or does not load properly, this is usually caused by an incomplete or failed frontend build. + +**Try the following:** + +1. Stop the dev server. +2. Run: `python -m scripts.start --dev` +3. If the issue persists, try: `python -m scripts.start --clean` +4. If necessary, run `yarn install` and restart the server. + +This is typically a frontend build or caching issue rather than a backend problem. + +### 404 when opening `/admin` + +If visiting `http://localhost:8181/admin` results in a **404 Page Not Found**, it usually means your account does not have the admin role assigned. + +The `/admin` page is only accessible to users with admin privileges. + +**Solution:** + +1. Start the dev server. +2. Go to: `http://localhost:8181/admin` +3. Assign yourself the **admin role** from the roles tab. +4. Restart the server if necessary. + +After assigning the admin role, the `/admin` page should load correctly. + +### Unable to generate translation opportunities locally + +If you are following the local development steps but are unable to generate and test translation opportunities (for example, for language contributions), it likely means the local testing steps weren’t followed correctly. + +To fix this: +1. Follow the official **Contributor Dashboard local development testing** instructions for generating translation opportunities. +2. Ensure your local server and dashboard environment are configured as per the contributor docs. +3. Repeat the setup steps from the Contributor Dashboard document when necessary. + +After completing those steps, you should be able to generate and view translation opportunities locally. + +### Webpack “Cannot resolve module ‘fs’” frontend error + +If your frontend build fails with an error like: +`Module not found: Error: Can't resolve 'fs' in ...` + +it means your frontend code is trying to import a **Node-only module (`fs`)** that cannot be bundled for the browser. + +**Cause:** +Frontend code shouldn’t import modules that only work in Node environments (like `fs`). + +**Solution:** +1. Remove the import of `fs` or other Node-only modules from the frontend code. +2. If you need file access or Node functionality, move that logic to backend code or expose it via an API. +3. Rebuild (`yarn` / `python -m scripts.start --clean`) after fixing the import. + +This will stop Webpack from attempting to bundle a Node-only module for the client. + +### oppia-angular-build container exits during install/run + +If the Oppia installation (e.g., `make build`, Docker startup, or `python -m scripts.start`) fails because the `oppia-angular-build` container exits unexpectedly or the build does not complete: + +**Possible fixes:** +1. Stop the server and **rebuild/restart the containers** so the build finishes cleanly. +2. If the container continues to exit or build fails repeatedly, run: `make clean` then re-build the server. +3. Ensure your internet connection is stable during dependency installation, as network issues can prevent required packages from downloading. + +This should help successfully build and start Oppia’s development environment without the container exiting mid-setup. + ## Linux From b50d6463093d90939b07ee364c7838e0ed21c249 Mon Sep 17 00:00:00 2001 From: Rohan Malhotra <139499925+rohanmalhotracodes@users.noreply.github.com> Date: Wed, 25 Feb 2026 22:04:25 +0530 Subject: [PATCH 2/4] Revise loading data and classroom creation steps Updated instructions for loading data and creating classrooms, including clarifications and reordering of steps. --- How-To-Load-Data.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/How-To-Load-Data.md b/How-To-Load-Data.md index 33b5a2e2..846e2232 100644 --- a/How-To-Load-Data.md +++ b/How-To-Load-Data.md @@ -14,14 +14,15 @@ ### Populating question opportunities -1. Start server and sign in as administrator (assume username “a”). +1. Start the server and sign in as administrator (assume username “a”). 2. Navigate to the Admin page. 3. Click the Roles tab. 4. In the Role editor, enter the admin username (“a”). Click Add Role, and add both the “Curriculum Admin” role and “Question Admin” role. -5. Go to http://localhost:8181/contributor-admin-dashboard and give submit question rights and review questions rights to your current username -6. Navigate back to the Admin page and navigate to the Activities tab. Click Load Data under Load dummy new structures data. -7. For the question opportunities to be valid, their corresponding topics must be part of a classroom topic. Navigate to the Config tab. Click Add element under [topic_id] (in the “The details for each classroom page.” section) and enter the topic id for the new topics that were created. (You can find a topic’s ID in its page URL from the Topic and Skills Dashboard). Make sure to click save at the bottom of the config page. -8. To enable the “Submit Question” tab for your user, make sure your signed in user is allowlisted for submitting question suggestions. +5. Go to http://localhost:8181/contributor-admin-dashboard and grant submit-question and review-question rights to your current username +6. Navigate back to the Admin page, then go to the Activities tab. Click Load Data under Load dummy new structures data. +7. For the question opportunities to be valid, their corresponding topics must be part of a classroom topic. Navigate to the classroom admin page: `http://localhost:8181/classroom-admin`. +8. Click **Add New Classroom** (or edit an existing classroom), and add the relevant **topic IDs** to the classroom. Save your changes. +9. To enable the “Submit Question” tab for your user, make sure your signed-in user is allowlisted for submitting question suggestions. ### Generating explorations 1. To generate data, we must first navigate to the admin page. We will automatically be redirected to the `ACTIVITIES` tab. @@ -34,15 +35,8 @@ 6. Generate a dummy math classroom. ### Creating a Classroom - -1. We must first navigate to the `CONFIG` tab in the admin page. -2. In this tab, there is a section `The details for each classroom page.` in which you will find a default math classroom that is filled out. -3. It has details about the classroom: - 1. Name - 2. URL Fragment - 3. topic list intro - 4. topic ids: The topic ids that should be included in the classroom are listed here. We can add to this by clicking on the `Add element` option. -4. More classrooms can be generated by clicking on the `Add element` option beneath this section. -5. Once the classroom details have been filled, to complete the process we must save changes by clicking the `Save` button at the bottom left corner of the `CONFIG` tab. -6. If the classroom has been created successfully, you will be able to see a message `Data successfully saved` at the bottom right corner of the screen. -7. The newly created classroom will be visible in the `Home` tab of the learner dashboard page, or we can directly access the classroom from the link `localhost:8181/learn/`. +1. Navigate to the Admin roles tab (`/admin`) and assign the **Curriculum Admin** role to yourself. +2. Go to the classroom admin page: `http://localhost:8181/classroom-admin`. +3. Click **Add New Classroom**, then add the classroom name and URL fragment. +4. Edit the classroom details and add the course details, topic intro, and **topic IDs** to the classroom. +5. Save your changes. The newly created classroom will be visible on the learner dashboard Home tab, or you can access it from `http://localhost:8181/learn/`. From 5a8d8242ccb76d3062b79bcc79bead9f470b65c8 Mon Sep 17 00:00:00 2001 From: Rohan Malhotra <139499925+rohanmalhotracodes@users.noreply.github.com> Date: Fri, 6 Mar 2026 10:16:27 +0530 Subject: [PATCH 3/4] docs: address troubleshooting review feedback --- Troubleshooting.md | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/Troubleshooting.md b/Troubleshooting.md index 0112a36b..f00b5e4e 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -39,7 +39,6 @@ Here are some general troubleshooting tips for Oppia. The platform specific tips - [404 when opening `/admin`](#404-when-opening-admin) - [Unable to generate translation opportunities locally](#unable-to-generate-translation-opportunities-locally) - [Webpack “Cannot resolve module ‘fs’” frontend error](#webpack-cannot-resolve-module-fs-frontend-error) -- [oppia-angular-build container exits during install/run](#oppia-angular-build-container-exits-during-installrun) - [Linux](#linux) - [OSError: \[Errno 2\] No such file or directory](#oserror-errno-2-no-such-file-or-directory) - [Pip: Cannot Import Name Main](#pip-cannot-import-name-main) @@ -346,9 +345,9 @@ If the dev server starts successfully but the page appears blank or does not loa **Try the following:** 1. Stop the dev server. -2. Run: `python -m scripts.start --dev` +2. Run: `python -m scripts.start` 3. If the issue persists, try: `python -m scripts.start --clean` -4. If necessary, run `yarn install` and restart the server. +4. If necessary, run `yarn install`, then restart the server with `python -m scripts.start`. This is typically a frontend build or caching issue rather than a backend problem. @@ -360,12 +359,12 @@ The `/admin` page is only accessible to users with admin privileges. **Solution:** -1. Start the dev server. +1. Start the dev server and sign in using the email suggested on first login (`testadmin@example.com`, which has implicit super-admin privileges). 2. Go to: `http://localhost:8181/admin` -3. Assign yourself the **admin role** from the roles tab. +3. From the Roles tab, assign the **admin role** to the account you want to use. 4. Restart the server if necessary. -After assigning the admin role, the `/admin` page should load correctly. +After signing in with the suggested email and assigning the admin role, the `/admin` page should load correctly. ### Unable to generate translation opportunities locally @@ -395,19 +394,6 @@ Frontend code shouldn’t import modules that only work in Node environments (li This will stop Webpack from attempting to bundle a Node-only module for the client. -### oppia-angular-build container exits during install/run - -If the Oppia installation (e.g., `make build`, Docker startup, or `python -m scripts.start`) fails because the `oppia-angular-build` container exits unexpectedly or the build does not complete: - -**Possible fixes:** -1. Stop the server and **rebuild/restart the containers** so the build finishes cleanly. -2. If the container continues to exit or build fails repeatedly, run: `make clean` then re-build the server. -3. Ensure your internet connection is stable during dependency installation, as network issues can prevent required packages from downloading. - -This should help successfully build and start Oppia’s development environment without the container exiting mid-setup. - - - ## Linux ### OSError: [Errno 2] No such file or directory From 56d2aad4e8ab2d041fcca024df0baff631b51fbd Mon Sep 17 00:00:00 2001 From: Rohan Malhotra <139499925+rohanmalhotracodes@users.noreply.github.com> Date: Thu, 26 Mar 2026 18:19:15 +0530 Subject: [PATCH 4/4] Update load-data steps and remove unsupported fs troubleshooting --- How-To-Load-Data.md | 2 +- Troubleshooting.md | 18 ------------------ 2 files changed, 1 insertion(+), 19 deletions(-) diff --git a/How-To-Load-Data.md b/How-To-Load-Data.md index 846e2232..7dc65249 100644 --- a/How-To-Load-Data.md +++ b/How-To-Load-Data.md @@ -21,7 +21,7 @@ 5. Go to http://localhost:8181/contributor-admin-dashboard and grant submit-question and review-question rights to your current username 6. Navigate back to the Admin page, then go to the Activities tab. Click Load Data under Load dummy new structures data. 7. For the question opportunities to be valid, their corresponding topics must be part of a classroom topic. Navigate to the classroom admin page: `http://localhost:8181/classroom-admin`. -8. Click **Add New Classroom** (or edit an existing classroom), and add the relevant **topic IDs** to the classroom. Save your changes. +8. Click **Add New Classroom** (or edit an existing classroom). Click **Add element** under `[topic_id]` in the "The details for each classroom page." section, then enter the topic ID for each new topic (you can find a topic's ID in its page URL from the Topic and Skills Dashboard). Make sure to click **Save** at the bottom of the config page. 9. To enable the “Submit Question” tab for your user, make sure your signed-in user is allowlisted for submitting question suggestions. ### Generating explorations diff --git a/Troubleshooting.md b/Troubleshooting.md index f00b5e4e..6382d858 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -38,7 +38,6 @@ Here are some general troubleshooting tips for Oppia. The platform specific tips - [Blank page or frontend not loading](#blank-page-or-frontend-not-loading) - [404 when opening `/admin`](#404-when-opening-admin) - [Unable to generate translation opportunities locally](#unable-to-generate-translation-opportunities-locally) -- [Webpack “Cannot resolve module ‘fs’” frontend error](#webpack-cannot-resolve-module-fs-frontend-error) - [Linux](#linux) - [OSError: \[Errno 2\] No such file or directory](#oserror-errno-2-no-such-file-or-directory) - [Pip: Cannot Import Name Main](#pip-cannot-import-name-main) @@ -377,23 +376,6 @@ To fix this: After completing those steps, you should be able to generate and view translation opportunities locally. -### Webpack “Cannot resolve module ‘fs’” frontend error - -If your frontend build fails with an error like: -`Module not found: Error: Can't resolve 'fs' in ...` - -it means your frontend code is trying to import a **Node-only module (`fs`)** that cannot be bundled for the browser. - -**Cause:** -Frontend code shouldn’t import modules that only work in Node environments (like `fs`). - -**Solution:** -1. Remove the import of `fs` or other Node-only modules from the frontend code. -2. If you need file access or Node functionality, move that logic to backend code or expose it via an API. -3. Rebuild (`yarn` / `python -m scripts.start --clean`) after fixing the import. - -This will stop Webpack from attempting to bundle a Node-only module for the client. - ## Linux ### OSError: [Errno 2] No such file or directory