docs: update Troubleshooting page with discussion-based fixes by rohanmalhotracodes · Pull Request #514 · oppia/oppia-web-developer-docs

rohanmalhotracodes · 2026-02-25T16:08:32Z

Summary of Changes

Added a note at the top of the troubleshooting page clarifying that it includes solutions from GitHub Discussions updated before February 25, 2026.
Added additional troubleshooting entries sourced from relevant GitHub Discussions.
Updated the Table of Contents to reflect the newly added sections.
Resolved Issue Update docs to reflect removal of config tab #434 by removing outdated references to the Config tab and restructuring the steps to match the current admin workflow.
Clarified and expanded multiple steps related to:
- Populating translation opportunities
- Populating question opportunities
- Generating explorations
- Creating classrooms
Ensured the instructions align with the current UI and role assignment process.
Cross-verified the updated steps using:
- The How to access Oppia webpages wiki documentation
- LEAP team / Contributor Dashboard documentation
- Admin Roles and Activities workflow
- Classroom Admin workflow
Updated outdated documentation links where necessary.
Fixed minor typos and terminology inconsistencies for consistency and professionalism:
- Opia → Oppia
- Github → GitHub

Although the typo fixes were not explicitly part of the original scope, they were minor consistency corrections and included here to avoid raising separate issues.

Issues Addressed

Fixes #207
Fixes #434

- Added note at top of page - Added troubleshooting entries from GitHub Discussions - Updated Table of Contents Fixes oppia#207

Updated instructions for loading data and creating classrooms, including clarifications and reordering of steps.

rohanmalhotracodes · 2026-02-25T16:47:17Z

@HardikGoyal2003 for #434 (comment)
The "Config tab" reference also appears in the Oppia Wiki page How-to-access-Oppia-webpages.md, which is part of the oppia/oppia.wiki repository.
Since this is not in oppia-web-developer-docs, should this issue be moved to the main Oppia repo instead?

I have included the other changes in this PR itself.

PS: Can we maybe raise a new issue in the main repo of Oppia since I have included the fixes needed in docs here itself.

rohanmalhotracodes · 2026-03-01T12:37:20Z

@jayam04 PTAL, gentle reminder.

rohanmalhotracodes · 2026-03-03T18:55:11Z

@jayam04 gentle ping.

jayam04

@rohanmalhotracodes Thank you for the updates. I have reviewed your changes.

jayam04 · 2026-03-05T18:04:31Z

Troubleshooting.md

+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.


@rohanmalhotracodes There is no option --dev

jayam04 · 2026-03-05T18:05:09Z

Troubleshooting.md

+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.


Specify, you must use email suggested on login for the first time to access /admin page.

jayam04 · 2026-03-05T18:06:19Z

Troubleshooting.md

+### 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:**


This was part of Docker setup, which we have already dropped. So, you can remove this.

rohanmalhotracodes · 2026-03-15T15:03:58Z

Gentle ping @jayam04 sir anything else you'd like me to addre

jayam04 · 2026-03-19T08:40:42Z

@rohanmalhotracodes Give me a day, I will review it.

jayam04

@rohanmalhotracodes Sorry for late review, left few comments.

jayam04 · 2026-03-24T15:56:40Z

How-To-Load-Data.md

+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.


Can you add this back?

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.

jayam04 · 2026-03-24T15:57:41Z

Troubleshooting.md

+### 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.


I am not sure about this. Can you link to Discussions/Issues that shows this approach helps troubleshoot the problem.

Removed the section as the points I wrote were too generic and there was no reliable way to determine whether they fix the issue

rohanmalhotracodes · 2026-03-26T13:01:51Z

PTAL @jayam04

docs: update Troubleshooting page with discussion-based fixes

01f43df

- Added note at top of page - Added troubleshooting entries from GitHub Discussions - Updated Table of Contents Fixes oppia#207

rohanmalhotracodes closed this Feb 25, 2026

rohanmalhotracodes deleted the docs/update-troubleshooting-discussions branch February 25, 2026 16:19

rohanmalhotracodes restored the docs/update-troubleshooting-discussions branch February 25, 2026 16:20

rohanmalhotracodes reopened this Feb 25, 2026

Revise loading data and classroom creation steps

b50d646

Updated instructions for loading data and creating classrooms, including clarifications and reordering of steps.

This was referenced Feb 25, 2026

Update the troubleshooting page on the wiki based on issues found from GitHub Discussions (with some light bookkeeping), and also provide general troubleshooting advice. #207

Open

Update docs to reflect removal of config tab #434

Open

HardikGoyal2003 requested a review from jayam04 February 27, 2026 12:16

HardikGoyal2003 assigned jayam04 Feb 27, 2026

jayam04 requested changes Mar 5, 2026

View reviewed changes

docs: address troubleshooting review feedback

5a8d824

jayam04 requested changes Mar 24, 2026

View reviewed changes

Update load-data steps and remove unsupported fs troubleshooting

56d2aad

Conversation

rohanmalhotracodes commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Issues Addressed

Uh oh!

rohanmalhotracodes commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rohanmalhotracodes commented Mar 1, 2026

Uh oh!

rohanmalhotracodes commented Mar 3, 2026

Uh oh!

jayam04 left a comment

Choose a reason for hiding this comment

Uh oh!

jayam04 Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

jayam04 Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

jayam04 Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

rohanmalhotracodes commented Mar 15, 2026

Uh oh!

jayam04 commented Mar 19, 2026

Uh oh!

jayam04 left a comment

Choose a reason for hiding this comment

Uh oh!

jayam04 Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

rohanmalhotracodes Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

jayam04 Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

rohanmalhotracodes Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rohanmalhotracodes commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rohanmalhotracodes commented Feb 25, 2026 •

edited

Loading

rohanmalhotracodes commented Feb 25, 2026 •

edited

Loading

rohanmalhotracodes Mar 26, 2026 •

edited

Loading