diff --git a/CHANGELOG.md b/CHANGELOG.md
index af55e34..2089362 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Support for Tcsh.
 - Added `--score` flag to `zoxide add`.
+- POSIX: add doctor to diagnose common issues.
 
 ### Changed
 
diff --git a/templates/posix.txt b/templates/posix.txt
index a1793ad..474eebe 100644
--- a/templates/posix.txt
+++ b/templates/posix.txt
@@ -43,6 +43,29 @@ if [ "${PS1:=}" = "${PS1#*\$(__zoxide_hook)}" ]; then
     PS1="${PS1}\$(__zoxide_hook)"
 fi
 
+# Report common issues.
+__zoxide_doctor() {
+{%- if hook != InitHook::Prompt %}
+    return 0
+{%- else %}
+    [ "${_ZO_DOCTOR:-1}" -eq 0 ] && return 0
+    case "${PS1:-}" in
+        *__zoxide_hook*) return 0 ;;
+    esac
+
+    _ZO_DOCTOR=0
+    \command printf '%s\n' \
+        'zoxide: detected a possible configuration issue.' \
+        'Please ensure that zoxide is initialized right at the end of your shell configuration file.' \
+        '' \
+        'If the issue persists, consider filing an issue at:' \
+        'https://github.com/ajeetdsouza/zoxide/issues' \
+        '' \
+        'Disable this message by setting _ZO_DOCTOR=0.' \
+        '' >&2
+{%- endif %}
+}
+
 {%- when InitHook::Pwd -%}
 \command printf "%s\n%s\n" \
     "zoxide: PWD hooks are not supported on POSIX shells." \
@@ -56,6 +79,8 @@ fi
 
 # Jump to a directory using only keywords.
 __zoxide_z() {
+    __zoxide_doctor
+
     if [ "$#" -eq 0 ]; then
         __zoxide_cd ~
     elif [ "$#" -eq 1 ] && [ "$1" = '-' ]; then
@@ -76,6 +101,7 @@ __zoxide_z() {
 
 # Jump to a directory using interactive search.
 __zoxide_zi() {
+    __zoxide_doctor
     __zoxide_result="$(\command zoxide query --interactive -- "$@")" && __zoxide_cd "${__zoxide_result}"
 }