docs: update Troubleshooting page with discussion-based fixes

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). 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
 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/<classroom-url-fragment>`.
+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/`.

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,11 @@ 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)
 - [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 +69,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,7 +322,59 @@ 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`
+3. If the issue persists, try: `python -m scripts.start --clean`
+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.
+
+### 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 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. From the Roles tab, assign the **admin role** to the account you want to use.
+4. Restart the server if necessary.
+
+After signing in with the suggested email and 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.
 
 ## Linux