Chapter 15: Common errors and troubleshooting
This introduction reframes programming errors as useful diagnostic information and emphasizes diagnosing and fixing them rather than avoiding them.
After this chapter you will be able to
- Errors as diagnostic information. Explain why encountering errors is normal in programming and why the useful response is to diagnose and fix them rather than treat them as failure.
- Missing Model Diagnosis. Explain that “model not found” means Ollama cannot find the requested model file locally, either because it was not downloaded or because the name was entered incorrectly. Describe using `ollama pull <model_name>` and `ollama list` to check and fix the problem.
- Connection refused meaning. Explain that a connection error means Python tried to reach Ollama but its server did not answer because the service is not running.
- Service recovery checks. Describe how to check whether Ollama is running, start it if necessary, and verify that the local service is reachable.
- Memory pressure symptoms and cause. Explain why an oversized local model may cause an explicit error or make the computer and model responses extremely slow.
- Reducing local model memory pressure. Describe how to respond to memory pressure by checking available memory and loaded models, choosing a smaller model, and freeing memory. State the section’s rule of thumb for model RAM requirements.
- Port conflict meaning. Explain that the error occurs when another process, often an existing Ollama server, is already listening on port 11434, so a second server cannot use that port.
- Existing process handling. Describe how to respond to the port conflict: usually use the existing Ollama instance; if it is stuck or not the intended service, identify the process using the port by its PID, stop it, force-kill it only if needed, and start Ollama again.
- Streamlit environment mismatch. Explain why Python may fail to find Streamlit even when it was installed, and describe how to check the active virtual environment, interpreter, and package installation before rerunning the app.
- Python version troubleshooting. Explain how an older Python version can cause library errors, and describe how to check the version and executable in use before creating a new virtual environment with the correct version.
- Three-step traceback reading. Apply the section’s three-step method: read the last line for the error type and description, find the line in your own code, then follow the calls to see how the error occurred.
- LLM-Assisted Error Diagnosis. Describe what to give an LLM when asking about a hard-to-diagnose error and how to use its answer.
- Graceful error handling. Explain how to use a try/except block to handle code that might fail, placing specific error catches before a general Exception catch and giving users actionable messages rather than raw tracebacks.
- Isolating chatbot startup failures. Describe how to find where the chatbot pipeline is failing by testing imports, the Ollama server connection, model availability, and Streamlit startup individually. Explain that debug_test.py is a diagnostic aid, not an automatic fix.
- Print debugging and output. Explain how temporary print statements help debug code by displaying selected variable values and showing which parts of the code are reached. Describe where to see debugging output in Streamlit.
- Logging levels and persistence. Explain how Python’s built-in logging module differs from print statements: it can write logs to files, control how much detail appears, and remain in the project when debugging is over. Describe why DEBUG suits debugging while WARNING or ERROR suits production.
- Flowchart First Diagnosis. Explain how to use the troubleshooting flowchart when something goes wrong: follow it step by step to identify the problem category before searching for solutions.
- Four-Level Troubleshooting Order. Apply the checklist in order: check the project environment, Ollama, code, and then Streamlit-specific issues, continuing to the next level as needed. Describe concrete checks that could reveal a problem at each level.
- Useful debugging help requests. Describe how to ask for help when you cannot resolve an error: give the command and full error, explain what you tried to do, what you expected and what happened, and include checks already performed and relevant environment details.
What it builds on
- Running the pull command (chapter 4) · Downloading a model with Ollama
- Listing downloaded models (chapter 4) · Listing downloaded models
- Understanding the model name format (chapter 4) · The model name format
- Starting the service (chapter 3) · Starting the Ollama service
- The size, capability, and memory tradeoff (chapter 4) · The relationship between model size and memory requirements.
- Checking running models (chapter 4) · Checking which models are running.
- Starting the Ollama service (chapter 3) · Starting and verifying the Ollama service
- Verifying activation (chapter 6) · Recognizing when a virtual environment is active.
Section by section
Introduction
This introduction reframes programming errors as useful diagnostic information and emphasizes diagnosing and fixing them rather than avoiding them.
- Errors as diagnostic information: Explain why encountering errors is normal in programming and why the useful response is to diagnose and fix them rather than treat them as failure.
Why it matters: Treating an error message as a clue gives you a way forward when code fails.
Key terms: error messages, diagnose, fix
15.1 Common errors and solutions
Introduces the following six common errors as a field guide for faster troubleshooting.
15.1.1 Error: Model not found
Explains how to diagnose and fix Ollama’s “model not found” error by checking whether the model is downloaded and whether its name and tag are correct.
- Missing Model Diagnosis: Explain that “model not found” means Ollama cannot find the requested model file locally, either because it was not downloaded or because the name was entered incorrectly. Describe using `ollama pull <model_name>` and `ollama list` to check and fix the problem.
Why it matters: These checks address the two causes of this common Ollama error. - Model Name And Tag Syntax: Describe Ollama’s `name:tag` format, including the colon, case-sensitive spelling, and the use of `latest` when a tag is omitted. Explain why an explicit tag selects a particular model variant.
Why it matters: A small difference in spelling or tag can make Ollama look for the wrong model.
Key terms: model not found, ollama pull, ollama list, name:tag, latest, model tag
15.1.2 Error: Connection refused
This section explains why Python may report a connection error with Ollama and how to check and restart the local service.
- Connection refused meaning: Explain that a connection error means Python tried to reach Ollama but its server did not answer because the service is not running.
Why it matters: The error points you toward the server’s availability rather than your Python prompt. - Service recovery checks: Describe how to check whether Ollama is running, start it if necessary, and verify that the local service is reachable.
Why it matters: Checking the service first gives you a concrete way to diagnose and fix this error.
Key terms: connection error, Ollama server, service, port 11434, ollama serve, Activity Monitor, http://localhost:11434, Ollama desktop app
15.1.3 Error: Out of memory
This section explains how to recognize when a local model exceeds available RAM and how to reduce memory pressure.
- Memory pressure symptoms and cause: Explain why an oversized local model may cause an explicit error or make the computer and model responses extremely slow.
Why it matters: Severe slowness can be a memory problem even when no error appears. - Reducing local model memory pressure: Describe how to respond to memory pressure by checking available memory and loaded models, choosing a smaller model, and freeing memory. State the section’s rule of thumb for model RAM requirements.
Why it matters: These checks and adjustments help you choose a model your Mac can run without severe slowdown.
Key terms: available RAM, memory, LLMs, available memory, loaded models, memory pressure, RAM
15.1.4 Error: Port already in use
Explains why Ollama reports that port 11434 is already in use and how to decide whether to reuse or stop the process occupying it.
- Port conflict meaning: Explain that the error occurs when another process, often an existing Ollama server, is already listening on port 11434, so a second server cannot use that port.
Why it matters: The error does not necessarily mean Ollama has failed; an existing instance may be available. - Existing process handling: Describe how to respond to the port conflict: usually use the existing Ollama instance; if it is stuck or not the intended service, identify the process using the port by its PID, stop it, force-kill it only if needed, and start Ollama again.
Why it matters: Checking before stopping a process avoids needlessly terminating a working Ollama service.
Key terms: port 11434, Ollama server, port already in use, process ID (PID), force-kill, existing Ollama instance
15.1.5 Error: Streamlit ModuleNotFoundError
This subsection explains why a Streamlit import error often comes from using the wrong Python environment and how to check and correct it.
- Streamlit environment mismatch: Explain why Python may fail to find Streamlit even when it was installed, and describe how to check the active virtual environment, interpreter, and package installation before rerunning the app.
Why it matters: Checking which Python runs the app helps you fix the mismatch rather than repeatedly installing Streamlit in the wrong environment.
Key terms: Streamlit, ModuleNotFoundError, virtual environment, Python interpreter, (venv)
15.1.6 Error: Python version problems
This section explains how to identify and fix Python-version problems that prevent Streamlit or the Ollama Python library from working.
- Python version troubleshooting: Explain how an older Python version can cause library errors, and describe how to check the version and executable in use before creating a new virtual environment with the correct version.
Why it matters: Checking which Python your project actually uses can resolve an error that reinstalling a package would not fix.
Key terms: Python version, Python executable, virtual environment, Python 3.9 or later
15.2 Reading error messages effectively
This section teaches a three-step way to read a Python traceback to identify an error and trace how the program reached it.
- Three-step traceback reading: Apply the section’s three-step method: read the last line for the error type and description, find the line in your own code, then follow the calls to see how the error occurred.
Why it matters: This method helps you turn an unfamiliar error into a specific place to investigate and an explanation of what failed.
Key terms: Python traceback, exception, error type, call chain
15.3 Debugging techniques
This section introduces using an LLM to suggest a likely cause of an error while protecting sensitive information and verifying its suggestions yourself.
- LLM-Assisted Error Diagnosis: Describe what to give an LLM when asking about a hard-to-diagnose error and how to use its answer.
Why it matters: An LLM can help narrow down an error, but checking its suggestion keeps you in control of the diagnosis. - Sensitive Debugging Information: Explain what information must stay out of a cloud-model debugging request and what the section recommends for sensitive projects.
Why it matters: Getting debugging help should not mean exposing sensitive information to a cloud model.
Key terms: LLM, traceback, hypothesis, cloud model, local Ollama model
15.3.1 Using try/except blocks
This section shows how try/except blocks let a program respond helpfully to errors instead of crashing.
- Graceful error handling: Explain how to use a try/except block to handle code that might fail, placing specific error catches before a general Exception catch and giving users actionable messages rather than raw tracebacks.
Why it matters: A useful error message helps someone recover when something goes wrong.
Key terms: try/except block, Exception, raw traceback
15.3.2 Step-by-step verification
This subsection teaches how to locate a chatbot startup failure by checking prerequisites separately rather than treating the pipeline as one failing step.
- Isolating chatbot startup failures: Describe how to find where the chatbot pipeline is failing by testing imports, the Ollama server connection, model availability, and Streamlit startup individually. Explain that debug_test.py is a diagnostic aid, not an automatic fix.
Why it matters: Checking one prerequisite at a time narrows down where to troubleshoot.
Key terms: chatbot pipeline, imports, Ollama server connection, model availability, Streamlit startup, debug_test.py
15.3.3 Print debugging
This section introduces print debugging as a way to inspect variable values and see which parts of a program run, with a Streamlit-specific tip.
- Print debugging and output: Explain how temporary print statements help debug code by displaying selected variable values and showing which parts of the code are reached. Describe where to see debugging output in Streamlit.
Why it matters: These quick checks help you locate where your program’s behavior differs from what you expected.
Key terms: print debugging, print statements, st.write()
15.3.4 Logging
This subsection explains why Python logging is useful for ongoing projects and how to change its detail level between debugging and production.
- Logging levels and persistence: Explain how Python’s built-in logging module differs from print statements: it can write logs to files, control how much detail appears, and remain in the project when debugging is over. Describe why DEBUG suits debugging while WARNING or ERROR suits production.
Why it matters: You can keep useful diagnostics in an application without showing every debug message to its users.
Key terms: logging module, logging level, DEBUG, WARNING, ERROR, production
15.4 The troubleshooting roadmap
This section gives two ways to start troubleshooting: categorize a problem with a flowchart and inspect issues reported by VS Code.
- Flowchart First Diagnosis: Explain how to use the troubleshooting flowchart when something goes wrong: follow it step by step to identify the problem category before searching for solutions.
Why it matters: Categorizing the problem gives you a more useful starting point than searching immediately. - VS Code Problem Inspection: Describe how to respond when VS Code marks a Python file with detected problems: open the Problems panel, read the line and message, fix or investigate the issue, and rerun the app.
Why it matters: The Problems panel gives you a specific issue to inspect rather than leaving you to guess.
Key terms: flowchart, problem category, VS Code, Problems panel
15.4.1 Four levels of troubleshooting
This section gives an ordered four-level checklist for narrowing down problems in a local AI application.
- Four-Level Troubleshooting Order: Apply the checklist in order: check the project environment, Ollama, code, and then Streamlit-specific issues, continuing to the next level as needed. Describe concrete checks that could reveal a problem at each level.
Why it matters: Checking one layer at a time helps you narrow down a bug instead of guessing at fixes.
Key terms: environment checks, Ollama checks, code checks, Streamlit-specific checks
15.4.2 A note on asking for help
The section shows how to ask for useful debugging help and how explaining code aloud can reveal a problem before asking.
- Useful debugging help requests: Describe how to ask for help when you cannot resolve an error: give the command and full error, explain what you tried to do, what you expected and what happened, and include checks already performed and relevant environment details.
Why it matters: A precise report lets other people help diagnose the problem rather than guess what went wrong. - Rubber duck debugging: Explain how describing code line by line to an imaginary listener can help you spot a problem yourself.
Why it matters: Talking through the code may help you find the bug without waiting for a reply.
Key terms: minimal reproducible example, full error message, environment, rubber duck debugging
15.5 Exercises
15.6 Summary
Where this is used later
- Final thoughts (chapter 18) · Reading error messages is one of the transferable debugging skills.
Concepts explained in this chapter
- OllamaOllama is a tool for downloading, running, and serving language models locally.
- virtual environmentA Python virtual environment is an isolated environment with its own installed packages.
- pipelineA sequence of processing stages in which each stage feeds its output to the next.
- ollama listAn Ollama command that lists the models available locally.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.