Troubleshooting

This runbook helps you diagnose and resolve common errors encountered when uploading leaf images, receiving predictions, or configuring the Plant Disease Predictor application, so you can restore normal API operation quickly.

This runbook covers errors related to image upload failures, model loading issues, unsupported file formats, malformed prediction responses, and runtime exceptions within the Plant Disease Predictor application. It does not cover network infrastructure failures, cloud hosting platform outages, browser-specific rendering issues, or retraining the CNN model itself.

Before working through this runbook, ensure you have the following in place:

• The Plant Disease Predictor application installed and previously running (see the Install and Launch guide)
• Access to the machine or container where the application is deployed
• The following files present in your application directory:
  • plant_disease_prediction_model.h5 — the pre-trained CNN model
  • class_indices.json — the class label mapping file
  • main.py — the Streamlit application entry point
• Python environment with the following packages installed:
  • tensorflow (the version used to train plant_disease_prediction_model.h5)
  • streamlit
  • Pillow
  • numpy
• If running via Docker, the Docker daemon must be active and the container must be running
• Terminal or shell access to view application logs

Work through each scenario below that matches your observed error. Stop as soon as your issue is resolved.

Scenario 1: Model fails to load on startup

This happens when plant_disease_prediction_model.h5 cannot be found or is corrupted. The application requires this file to be present in the same directory as main.py before it can serve any predictions.

1. Check that plant_disease_prediction_model.h5 exists in your working directory:

   Copy

   ls -lh plant_disease_prediction_model.h5
   

   Success looks like: The file is listed with a non-zero file size.

2. If the file is missing, restore it from your backup or model artifact storage. If it exists but the error persists, verify the file is not corrupted by checking it loads in isolation:

   Copy

   import tensorflow as tf
   model = tf.keras.models.load_model("plant_disease_prediction_model.h5")
   print(model.summary())
   

   Success looks like: The model summary prints without raising an exception.

3. Restart the Streamlit application:

   Copy

   streamlit run main.py
   

   Success looks like: The application starts and displays "Plant Disease Classifier" in the browser without error messages.

Scenario 2: class_indices.json not found or invalid

The application reads class_indices.json at startup to map numeric prediction outputs to human-readable disease names. A missing or malformed file causes a crash before any image can be processed.

1. Confirm the file exists in the working directory:

   Copy

   ls -lh class_indices.json
   

   Success looks like: The file is listed with a non-zero file size.

2. Validate that the file contains valid JSON with string keys mapping to class names:

   Copy

   python -c "import json; d = json.load(open('class_indices.json')); print(list(d.items())[:3])"
   

   Success looks like: A list of key-value pairs such as [('0', 'Apple___Apple_scab'), ('1', 'Apple___Black_rot'), ...] prints without error.

3. If the file is malformed, restore it from your source repository or artifact storage, then restart the application.

Scenario 3: Image upload is rejected or produces no prediction

The application accepts only jpg, jpeg, and png image formats. Uploads in any other format are silently ignored by the file uploader widget.

1. Confirm your image file uses one of the supported extensions: .jpg, .jpeg, or .png.

2. If the extension is correct but the upload still fails, verify the image can be opened by Pillow:

   Copy

   from PIL import Image
   img = Image.open("your_leaf_image.jpg")
   print(img.size, img.mode)
   

   Success looks like: The image size and mode print (e.g., (800, 600) RGB) without raising an exception.

3. If Pillow raises an error (e.g., UnidentifiedImageError), the file may be corrupted or mislabeled. Use a valid image file and retry the upload.

4. After uploading a valid image, click the Classify button. The prediction appears in the right column. Success looks like: A green success banner displays text in the format Prediction: <disease_name>.

Scenario 4: Prediction returns an unexpected or incorrect class name

The model resizes every uploaded image to 224×224 pixels and normalizes pixel values to the [0, 1] range before inference. Images that are heavily distorted, very low resolution, or do not contain a visible leaf may produce low-confidence or incorrect predictions.

1. Ensure the image clearly shows a single leaf against a contrasting background.

2. Verify that the preprocessing pipeline runs without error on your image:

   Copy

   from PIL import Image
   import numpy as np
   
   img = Image.open("your_leaf_image.jpg").resize((224, 224))
   img_array = np.array(img).astype('float32') / 255.
   print(img_array.shape, img_array.min(), img_array.max())
   

   Success looks like: Output is (224, 224, 3) 0.0 1.0 (values may vary but shape must be correct).

3. If the shape is not (224, 224, 3), the image may be grayscale or have an alpha channel. Convert it to RGB before uploading:

   Copy

   img = Image.open("your_leaf_image.png").convert("RGB")
   img.save("your_leaf_image_rgb.jpg")
   

   Then retry the upload with the converted file.

Scenario 5: Application crashes or hangs during prediction

This typically indicates a TensorFlow runtime error, insufficient memory, or a version mismatch between the saved model and the installed TensorFlow version.

1. Check the terminal where Streamlit is running for a full traceback. Note the exact exception type and message.

2. Confirm your TensorFlow installation can perform inference independently:

   Copy

   import tensorflow as tf
   import numpy as np
   
   model = tf.keras.models.load_model("plant_disease_prediction_model.h5")
   dummy_input = np.zeros((1, 224, 224, 3), dtype='float32')
   result = model.predict(dummy_input)
   print(result.shape)
   

   Success looks like: An array shape such as (1, N) prints, where N is the number of disease classes.

3. If you receive a memory error, close other applications consuming GPU or RAM and retry.

4. If the error references a model format incompatibility, ensure the TensorFlow version installed matches the version used to save the .h5 model file.

After completing the relevant steps above, confirm the application is fully operational by performing an end-to-end test:

1. Launch the application and confirm the title Plant Disease Classifier appears in your browser without any error banners or tracebacks in the terminal.

2. Upload a valid .jpg, .jpeg, or .png leaf image using the file uploader widget.

3. Click the Classify button.

4. Confirm that:

   • A thumbnail of your image appears in the left column.
   • A green success banner appears in the right column displaying text in the format:
     Copy

     Prediction: <disease_class_name>
     

   • No exceptions or warnings appear in the terminal running Streamlit.

If all four conditions are met, the application is functioning correctly.

If your troubleshooting actions have made the application state worse (for example, you accidentally modified main.py, class_indices.json, or the model file), use the following steps to restore a known-good state:

1. Stop the running application:

   Copy

   # Press Ctrl+C in the terminal running Streamlit, or stop the Docker container:
   docker stop <your_container_name>
   

2. Restore any modified files from your version control system:

   Copy

   git checkout -- main.py class_indices.json
   

3. If plant_disease_prediction_model.h5 was overwritten or deleted, restore it from your model artifact storage or backup location. This file is typically not tracked in version control due to its size.

4. If you are using Docker, pull the last known-good image and restart the container:

   Copy

   docker pull <your_image_name>:<last_known_good_tag>
   docker run <your_image_name>:<last_known_good_tag>
   

5. Re-run the Verification steps to confirm the restored state is healthy.

If you have completed all applicable steps in this runbook and the application is still not functioning correctly, escalate the issue with the following information:

Who to contact:

What to provide when escalating:

• The full error traceback copied from the Streamlit terminal output
• The output of the following diagnostic commands:
  Copy

  python --version
  python -c "import tensorflow as tf; print(tf.__version__)"
  python -c "import streamlit as st; print(st.__version__)"
  python -c "import PIL; print(PIL.__version__)"
  ls -lh plant_disease_prediction_model.h5 class_indices.json
  

• A description of the image you were attempting to upload (format, approximate resolution, subject matter)
• The steps you already attempted from this runbook and their outcomes
• Whether the application is running directly via streamlit run main.py or inside a Docker container, and if Docker, the output of docker logs <container_name>