Appendix D. Troubleshooting Common Errors

This appendix is a practical troubleshooting guide for the kinds of failures that most often appear in the book’s examples. It emphasizes that problems usually come from a small set of repeat causes: missing configuration values, absent packages, API changes, or data that does not match what the code expects. Rather than treating every issue as unique, it organizes errors by area and gives the symptom, likely cause, and a direct fix, often pointing back to setup guidance when a fuller installation is needed.

Many of the problems begin with environment setup and authentication. Common fixes include confirming that Python 3.8+ is installed, using the right command names on different systems, activating the virtual environment, reinstalling dependencies, and making sure Jupyter is using the same interpreter as the rest of the project. For API access, the text stresses loading environment variables correctly, checking that keys are named and stored properly, verifying that the secret is actually available without printing it, and updating or replacing expired keys or missing billing setup when requests fail.

The appendix also covers runtime issues across OpenAI calls, web scraping, data handling, and PostgreSQL. It explains how to handle SDK version mismatches, retired model names, rate limits, timeout errors, blocked sites, JavaScript-rendered pages, missing files, absent Excel engines, missing dictionary keys, unexpected NaN values, connection problems, bad credentials, missing drivers, and databases that have not been created yet. The overall message is to diagnose by category, confirm assumptions about version, data shape, and connectivity, and then apply simple corrective steps such as upgrading packages, adjusting code to newer APIs, adding retries, or handling missing data more safely.

• Read the full error message, not just the last line. The actual cause is often a few lines up.
• Re-run the failing step in isolation in a fresh notebook cell so you can see exactly what input it received.
• Print the shape of your data (the JSON keys, the DataFrame columns, the response status code) before the line that fails. Most data-engineering bugs are shape mismatches, not logic errors.
• Check the chapter's README.md and setup/ folder in the repository for chapter-specific guidance, and open an issue on the GitHub repository for persistent problems.

FAQ