ValueError: substring not found (Fix)

ValueError: substring not found means Python could not find the piece of text you asked for inside a string.

This error usually appears when you use string methods like index() that expect a match. If the substring is missing, Python raises an error instead of returning a special value.

This page shows:

  • what the error means
  • why it happens
  • examples that cause it
  • simple ways to fix it

Quick fix

If the substring may be missing, check first before calling index():

text = "hello world"
sub = "python"

if sub in text:
    pos = text.index(sub)
    print(pos)
else:
    print("Substring not found")

Output:

Substring not found

Use in before index() if the substring may be missing. You can also use find() when you want -1 instead of an error.

What this error means

This error means Python could not find the text you searched for inside a string.

A substring is just a smaller piece of text inside a larger string.

This usually happens with str.index() or similar methods that raise an exception when no match is found.

When this error happens

You will often see this error in cases like these:

  • Calling text.index("something") when that text is not present
  • Searching with the wrong capitalization, such as "Hello" vs "hello"
  • Searching text that includes extra spaces or hidden characters
  • Using user input that does not match the string exactly

Example that causes the error

Here is a minimal example:

word = "apple"
print(word.index("z"))

"z" is not inside "apple", so Python raises an error.

Error:

ValueError: substring not found

Fix 1: Check before using index()

A simple fix is to test whether the substring exists before calling index().

text = "banana"
sub = "na"

if sub in text:
    position = text.index(sub)
    print(position)
else:
    print("Substring not found")

Output:

2

Why this works:

  • sub in text returns True if the substring exists
  • index() only runs when the substring is present
  • this avoids the ValueError

This is one of the clearest beginner-friendly solutions. If you want more on this approach, see how to check if a string contains a substring in Python.

Fix 2: Use find() instead of index()

If a missing substring is normal in your program, use str.find() instead.

find() returns -1 when the substring is not found.

text = "hello world"
sub = "python"

position = text.find(sub)

if position != -1:
    print(position)
else:
    print("Substring not found")

Output:

Substring not found

This is useful when:

  • you expect some searches to fail
  • you do not want an exception
  • you want to handle the result yourself

Difference:

  • index() → raises ValueError
  • find() → returns -1

Fix 3: Normalize the text before searching

Sometimes the substring is there logically, but the text does not match exactly.

Common problems include:

  • uppercase vs lowercase letters
  • extra spaces
  • newline characters
  • hidden characters from file or user input

Use lower() for case-insensitive matching

text = "Hello World"
sub = "hello"

if sub.lower() in text.lower():
    print("Found")
else:
    print("Not found")

Output:

Found

If needed, learn more about lower().

Use strip() to remove extra spaces

text = "  apple  "
sub = "apple"

if sub == text.strip():
    print("Match")
else:
    print("No match")

Output:

Match

strip() removes whitespace from the start and end of a string. See also how to remove whitespace from a string in Python and the strip() method reference.

Use repr() to spot hidden characters

print() can hide useful details. repr() shows them more clearly.

text = "apple\n"
sub = "apple"

print(repr(text))
print(repr(sub))
print(sub in text)

Output:

'apple\n'
'apple'
True

This is helpful when debugging file input or copied text.

Debugging steps

If you are not sure why the error is happening, try these steps:

  1. Print the full string you are searching in.
  2. Print the exact substring you are searching for.
  3. Check capitalization, spaces, punctuation, and line breaks.
  4. Test whether the substring actually exists with substring in text.

Useful debugging commands:

print(text)
print(substring)
print(repr(text))
print(repr(substring))
print(substring in text)
print(text.find(substring))

These checks often reveal the real problem quickly.

Related methods to understand

These string methods are closely related:

  • str.index() raises ValueError if the substring is not found
  • str.find() returns -1 if the substring is not found
  • str.rindex() searches from the right side and raises ValueError if not found
  • str.rfind() searches from the right side and returns -1 if not found

Choose the method based on how you want your program to behave when there is no match.

Common mistakes

These are common reasons for this error:

  • Using str.index() for text that may not exist
  • Case mismatch between the string and substring
  • Leading or trailing spaces in either value
  • Unexpected newline characters from file input
  • Assuming user input always matches expected text

If you are seeing many different ValueError problems, it may also help to read ValueError in Python: causes and fixes.

FAQ

What causes "ValueError: substring not found" in Python?

It usually happens when you use str.index() and the substring does not exist in the string.

How do I avoid this error?

Check with in first, or use find() if you want a safe return value instead of an exception.

What is the difference between index() and find()?

index() raises an error if not found. find() returns -1.

Can spaces or capitalization cause this error?

Yes. String searches must match exactly unless you clean or normalize the text first.

See also