Error Messages and How to Read Them
Testing and debugging are essential phases where you verify that your program works and fix errors that prevent it from working correctly.
A Failed First Run
A first program rarely works perfectly on the first attempt. This is normal, including in professional programming. The first run is not the end of the process; it is a testing event that gives you information about what the program actually does.
Testing checks whether a program works as intended. Debugging is the work of fixing errors that prevent it from working correctly. These activities are connected: testing reveals a problem, debugging addresses it, and another test checks the result.
The Two Layers in a Backup Failure
A backup program can involve two layers. The Python program is one layer. The system command that Python calls to compress and archive files is another. When the backup operation fails, the error may be in the command itself or in the way the Python program calls that command.
When the backup program fails, test the system command manually before changing Python code at random. If the command works manually but fails when run by the program, the problem is in the Python code or in how that code calls the command. If the command also fails manually, investigate the command layer instead.
Reading the Reported Failure
An error message is useful because it reports that something did not work at a particular stage of the process. Begin by identifying who is reporting the failure: the command-line system command or the Python program. This distinction narrows the place where you should look.
| Question | Command-line problem | Python program problem |
|---|---|---|
| Where is the failure? | In the system command used for the backup operation | In the Python program or in how it calls the command |
| How do you isolate it? | Run the command manually and observe whether it works | Compare the program's behavior with the successful manual command |
| What is the next focus? | Investigate the command layer | Debug the Python code or its call to the command |
Use the manual command test to separate the two possible layers.
Design, Syntax, and Implementation
Once you know where the failure occurs, decide what kind of problem you are facing. A design flaw means the intended solution needs reconsideration. An implementation mistake means the design may be suitable, but the code does not carry it out correctly. A syntax problem is a code-grammar problem: the program is not written in the form the language expects. These categories help you choose between returning to design and debugging the code.
The practical question is not simply “What line should I change?” Ask instead: Is the planned solution itself unsuitable? Is the code written in an unacceptable form? Or does the code run but behave differently from the intended design? The answer determines whether you return to design or continue debugging the implementation.
The Testing and Debugging Cycle
A Backup Program That Does Not Create the Backup
A backup program runs, but the backup operation fails. How should the problem be isolated?
- 1Start with the failure
Treat the failed backup as evidence that one of two layers needs investigation: the system command or the Python program that calls it.
- 2Test the command manually
Run the backup command outside the Python program. This separates the command itself from the program's use of it.
- 3Interpret the result
If the command works manually, focus debugging on the Python code or on how it calls the command. If the command fails manually too, focus on the command layer.
- 4Choose design or debugging
If the intended backup approach is unsuitable, return to the design phase. If the approach is suitable but the code does not implement it correctly, debug the implementation.
- 5Test again
After making a correction, test the program again. Testing and debugging repeat until the program works correctly.
The manual command test prevents random changes by identifying which layer needs attention and whether the problem calls for redesign or code debugging.
What do you think happens?
A backup command works when tested manually but fails when the Python program runs it. Which layer should you debug first?
Reveal answer
The Python program and how it calls the command
A successful manual test isolates the command as working in that test. The remaining focus is the Python code or the way the program calls the command.
Mistakes Beginners Make
Common mistake Expecting the first run to work perfectly
What it looks likeTreating a failed first attempt as unusual or as proof that the whole approach is hopeless.
Why it failsFirst programs commonly fail on the first run, and repeated testing and debugging are normal parts of programming.
Do this insteadUse the failure as information and begin a systematic troubleshooting cycle.
Common mistake Changing Python code before testing the command manually
What it looks likeEditing several parts of the backup program without checking whether the underlying command works by itself.
Why it failsThe backup program contains both a Python layer and a system-command layer, so changing the wrong layer can waste effort.
Do this insteadTest the command manually first and use the result to choose the layer to investigate.
Common mistake Assuming every failure is an implementation mistake
What it looks likeDebugging code even when the intended backup solution itself is unsuitable.
Why it failsSome problems are design flaws and require returning to the design phase rather than only changing code.
Do this insteadDecide whether the intended solution is sound before spending more time debugging its implementation.
Common mistake Treating testing and debugging as one-time activities
What it looks likeMaking one correction and assuming the program is finished without testing again.
Why it failsTesting and debugging form a cycle that repeats until the program works correctly.
Do this insteadRun another test after each meaningful correction.
Troubleshooting Practice
A backup program fails. The system command also fails when you test it manually. Identify the layer that should be investigated first and explain why.
Hints
- Compare the manual test result with the result from the Python program.
- The purpose of the manual test is to separate the command layer from the Python calling layer.
A backup program uses an approach that cannot meet the intended backup goal. Should you continue debugging the existing code or return to the design phase? Explain the category of problem.
Hints
- Ask whether the intended solution is suitable before asking whether the code implements it correctly.
- The source distinguishes design flaws from implementation mistakes.
Key Takeaways
- A first program failing is normal; testing and debugging are expected parts of programming.
- A backup program may fail in the Python layer or in the system-command layer.
- Test the command manually to isolate which layer contains the problem.
- Separate design flaws from syntax problems and implementation mistakes so that you know whether to redesign or debug.
- Testing, finding an error, making a correction, and testing again form a repeating cycle.