Debugging a Bash Script

Debugging and troubleshooting in Bash scripts is a crucial skill for any scriptwriter or system administrator.

Understanding the Script's Purpose

  1. Clear Goals: Before exploring into debugging, articulate the script's intended behavior and expected outcomes. This clarity will guide your troubleshooting efforts.
  2. Functionality Breakdown: If the script is large or complex, decompose it into smaller, logical units to focus on specific areas during debugging.

Using Built-in Bash Debugging Tools

  1. Echoing Variables and Expressions: Strategically insert echo statements to print variable values, string operations, and command outputs at key points in the script. This provides insights into data flow and helps pinpoint where values go wrong.
  2. Utilizing set -x: Run the script with the -x flag (e.g., bash -x This verbose mode prints each command before execution, revealing the script's inner workings and command expansions.
  3. Subshells for Localized Debugging: Use (set -x; <command>) or sh -x <command> to enable debugging within smaller code blocks without affecting the entire script.
  4. Tracing with trap: Set a debugging trap using trap 'echo $BASH_LINENO: "$BASH_COMMAND"' DEBUG to track line numbers and commands as the script executes.

Debugging Common Errors

  1. Syntax Errors: Double-check for correct syntax, spelling, and punctuation, especially in command and conditional structures.
  2. Logic Errors: Review the script's flow and reasoning. Test with different inputs to isolate unexpected behavior. Use echo statements to inspect intermediate values.
  3. Runtime Errors: Errors occurring during execution might be due to incorrect file or directory paths, permission issues, environmental variables, or external commands failing. Handle these appropriately using if statements, checking return codes, or providing default values.

Here are some techniques, tools, and examples to help you understand and address common issues in your Bash scripts:

Enable Debugging

Use the set -x option at the beginning of your script to enable debugging. This will print each command and its arguments to the standard error output before executing it.

#!/bin/bash set -x # rest of the script

Print Statements

Insert echo statements at different points in your script to print variable values, messages, or any other information that can help you trace the flow of execution.

#!/bin/bash variable="Hello" echo "Value of variable: $variable"

Redirect Output

Redirect output to a log file for further analysis.

#!/bin/bash exec > logfile.txt 2>&1 # rest of the script

Check Exit Codes

Examine the exit codes of commands using the $? variable.

#!/bin/bash ls /nonexistent_directory if [ $? -ne 0 ]; then echo "Error: Directory does not exist." fi

Use set -e for Immediate Exit

Set set -e to make the script exit immediately if any command exits with a non-zero status.

#!/bin/bash set -e # rest of the script

Check Syntax Errors

Use bash -n to check for syntax errors without executing the script.

bash -n


Utilize tools like ShellCheck to identify common scripting issues.



Implement logging in your script to record important events and errors.

#!/bin/bash log_file="script.log" echo "Script started at $(date)" >> $log_file # rest of the script

Debugging with trap

Use trap to catch signals and execute commands for debugging purposes.

#!/bin/bash trap 'echo Script interrupted; exit 1' INT TERM # rest of the script

Conditional Debugging

Execute specific commands only when a certain condition is met.

#!/bin/bash DEBUG=true if [ "$DEBUG" = true ]; then echo "Debugging information" # additional debugging commands fi
Example Script:

Here's an example script incorporating some of these techniques:

#!/bin/bash set -x # Enable debugging log_file="script.log" echo "Script started at $(date)" >> $log_file variable="Hello" echo "Value of variable: $variable" ls /nonexistent_directory if [ $? -ne 0 ]; then echo "Error: Directory does not exist." >> $log_file fi set +x # Disable debugging echo "Script completed at $(date)" >> $log_file

This script uses debugging, logging, and error checking techniques to enhance its robustness and troubleshoot potential issues. Remember, adapting these techniques based on the specific needs and challenges of your script is crucial for effective debugging and troubleshooting.

Advanced Debugging Techniques

GDB, the GNU Debugger

GDB, the GNU Debugger, is a powerful tool for debugging complex scenarios in programming. It allows developers to set breakpoints, inspect variables, step through code execution, and analyze interactions, making it invaluable for identifying and resolving issues in intricate software systems.

Debuggers from IDEs

IDEs such as Visual Studio Code and PyCharm offer built-in debuggers tailored for Bash scripts. These debuggers provide an integrated and user-friendly environment for setting breakpoints, inspecting variables, and navigating through code, streamlining the debugging process within the familiar interface of the integrated development environment.

Tips for Effective Troubleshooting

  1. Start Simple: Begin with basic debugging tools like echo and set -x. Only move to more advanced techniques if necessary.
  2. Isolate the Issue: Try to narrow down the problematic section by commenting out parts of the script or using smaller test cases.
  3. Print Debugging Messages: Include meaningful comments and print statements to log information and variable values.
  4. Ask for Help: Search online forums or communities for solutions to common errors, or seek assistance from experienced Bash script developers.

Additional Notes


In scripting, thorough comments elucidate logic and decision points, enhancing future comprehension and facilitating collaboration. Clear documentation not only aids your own understanding but also invites contributions from others, maintaining a collaborative and maintainable codebase.


Effective testing involves creating unit and integration tests to validate various script components, detecting errors in early development stages. By implementing robust testing practices, scriptwriters can ensure reliability and identify issues promptly, contributing to the creation of more resilient and error-free scripts.


Enhancing script organization and simplifying debugging, modularity involves breaking down intricate scripts into smaller, manageable functions or modules. This approach promotes code reuse, readability, and easier maintenance, enabling efficient collaboration and encouraging a more maintainable and scalable scripting project.

Version Control

Utilizing version control systems like Git is crucial for tracking script changes, reverting to previous versions, and collaborating seamlessly. Version control ensures a comprehensive history of code alterations, mitigates the risk of data loss, and facilitates collaborative work, making it an essential tool for effective script development and maintenance.


Debugging and troubleshooting in Bash scripts involves using techniques such as enabling debugging with tools like GDB or built-in IDE debuggers, incorporating print statements, checking exit codes, and implementing logging. Effective documentation, testing, modularity, and version control further contribute to efficient identification and resolution of issues in Bash scripts, ensuring reliability and maintainability.