BadLocationException in Java

Learn what BadLocationException in Java is, why it occurs in text components like JTextArea and JTextPane, and how to fix it. Includes complete examples and output explanation.

This reference explains BadLocationException in Java through its syntax, examples and boundaries. Use the linked course lessons when the surrounding Java concepts are unfamiliar.

BadLocationException is a checked exception in Java, found in the javax.swing.text package. It is thrown to indicate that an invalid position (offset) was passed to a method in a document or text component such as JTextArea, JTextPane, or Document.

This exception helps prevent accidental access to characters or positions outside the valid range of a document.

package javax.swing.text;

public class BadLocationException extends Exception {
    public BadLocationException(String s, int offs) {
        super(s);
        this.offs = offs;
    }

    public int offsetRequested() {
        return offs;
    }

    private int offs;
}

As it extends Exception, BadLocationException is a checked exception and must be handled or declared.

This exception is thrown when:

• You try to insert, remove, or retrieve text at an index that doesn't exist in the Document.
• You pass a negative index or an index greater than the document length.

Common methods that may throw it:

• Document.getText(int offset, int length)
• Document.insertString(int offset, String text, AttributeSet attr)
• Document.remove(int offset, int length)

Let’s build a simple Swing program that uses a JTextArea and accesses its underlying document. We’ll demonstrate what happens when we try to retrieve text from an invalid position.

import javax.swing.*;
import javax.swing.text.*;

public class BadLocationExceptionDemo {

    public static void main(String[] args) {
        // Step 1: Create a JTextArea
        JTextArea textArea = new JTextArea();
        textArea.setText("Hello World!");

        // Step 2: Get the document from the text area
        Document doc = textArea.getDocument();

        // Step 3: Try to retrieve a portion of text using an invalid offset
        try {
            // Document has 12 characters ("Hello World!")
            // Let's try to access from offset 20 (invalid)
            String result = doc.getText(20, 5);
            System.out.println("Extracted Text: " + result);
        } catch (BadLocationException e) {
            System.out.println("Caught BadLocationException:");
            System.out.println("Message: " + e.getMessage());
            System.out.println("Invalid Offset: " + e.offsetRequested());
        }
    }
}

Java · example discussed here

import javax.swing.*;
import javax.swing.text.*;

public class BadLocationExceptionDemo {

    public static void main(String[] args) {
        // Step 1: Create a JTextArea
        JTextArea textArea = new JTextArea();
        textArea.setText("Hello World!");

        // Step 2: Get the document from the text area
        Document doc = textArea.getDocument();

        // Step 3: Try to retrieve a portion of text using an invalid offset
        try {
            // Document has 12 characters ("Hello World!")
            // Let's try to access from offset 20 (invalid)
            String result = doc.getText(20, 5);
            System.out.println("Extracted Text: " + result);
        } catch (BadLocationException e) {
            System.out.println("Caught BadLocationException:");
            System.out.println("Message: " + e.getMessage());
            System.out.println("Invalid Offset: " + e.offsetRequested());
        }
    }
}

Caught BadLocationException:
Message: Invalid location
Invalid Offset: 20

Java · example discussed here

import javax.swing.*;
import javax.swing.text.*;

public class BadLocationExceptionDemo {

    public static void main(String[] args) {
        // Step 1: Create a JTextArea
        JTextArea textArea = new JTextArea();
        textArea.setText("Hello World!");

        // Step 2: Get the document from the text area
        Document doc = textArea.getDocument();

        // Step 3: Try to retrieve a portion of text using an invalid offset
        try {
            // Document has 12 characters ("Hello World!")
            // Let's try to access from offset 20 (invalid)
            String result = doc.getText(20, 5);
            System.out.println("Extracted Text: " + result);
        } catch (BadLocationException e) {
            System.out.println("Caught BadLocationException:");
            System.out.println("Message: " + e.getMessage());
            System.out.println("Invalid Offset: " + e.offsetRequested());
        }
    }
}

• The document contains "Hello World!" which is 12 characters long.
• Calling doc.getText(20, 5) tries to access characters starting at index 20, which does not exist.
• This throws a BadLocationException, and we catch it and print the message along with the invalid offset.

To prevent this exception, always check the document length and bounds before accessing or modifying text. Here’s how:

int length = doc.getLength();
if (offset >= 0 && offset + requestedLength <= length) {
    String text = doc.getText(offset, requestedLength);
    System.out.println("Safe Text: " + text);
} else {
    System.out.println("Offset or length out of bounds.");
}

BadLocationException is crucial in:

• Text editors built with Swing (e.g., Notepad clones)
• Form input validation with text manipulation
• Custom code editors or log viewers in Java GUIs

• Use Document.getLength() to get the current size of the document.
• Never assume the length of a JTextComponent's content — always validate indexes before using them.
• Use try-catch blocks when calling methods that may throw BadLocationException.

• Passing negative values to offset or length in getText or remove
• Accessing text beyond the end of the document
• Assuming hardcoded offsets will always be valid after text is modified

• BadLocationException is part of the javax.swing.text package and is used to handle invalid offsets in text documents.
• It is a checked exception and must be handled properly using try-catch or method declarations.
• Occurs mostly when accessing or modifying content in Swing components like JTextArea or JTextPane.
• Always verify bounds using Document.getLength() before accessing the content.

Although BadLocationException is a specific exception tied to Java Swing’s document model, it teaches a valuable lesson: never trust assumptions about input sizes or document content. Always validate before access. Whether you’re building simple editors or complex GUI tools, understanding this exception is essential for building stable, user-friendly interfaces.

Check the example’s types, inputs and documented behavior before copying it into an application. Some APIs require external libraries, files or platform services; consult their setup notes.

Related explanations: Java Data Types - Primitive and Non-Primitive, Java Class - Blueprint of Objects, Exceptions in Java Introduction.

Supporting documentation: Official Java learning guide.