Common issues with LaTeX files and how to solve them

Introduction

LaTeX (pronounced “lay-tech” or “lah-tech”) is a document preparation system used for creating documents with complex formatting, such as academic papers, research articles, theses, books, and more. LaTeX is popular because of its ability to produce professional-looking documents with consistent and high-quality typesetting.

A LaTeX file is a plain text file that contains a combination of text content and LaTeX commands. These commands are used to define the structure, formatting, and layout of the document. When you compile a LaTeX file using a LaTeX compiler, it processes the commands and produces a formatted output document, typically in PDF format.

Here’s a basic example of what a simple LaTeX file might look like:

 1\documentclass{article} % Specifies the type of document (article, book, etc.)
 2\title{Introduction to LaTeX}
 3\author{John Doe}
 4\date{\today}
 5
 6\begin{document}
 7\maketitle
 8
 9\section{Introduction}
10LaTeX is a typesetting system commonly used for documents with complex formatting.
11
12\section{Features}
13\begin{itemize}
14  \item Consistent and professional-looking output.
15  \item Automatic numbering and cross-referencing.
16  \item Support for mathematical equations and symbols.
17\end{itemize}
18
19\end{document}

In this example, the \documentclass command specifies the type of document, and the content of the document is defined within further the document environment. LaTeX provides you with different packages and commands to control aspects of the document’s appearance, structure, and content. This makes it a powerful tool for creating documents that require precise formatting and layout.

Pros and cons of LaTeX files

LaTeX offers several advantages and some disadvantages compared to other document preparation systems. Learn them to see if this format is the right choice for your task.

Pros	Cons
LaTeX provides high-quality typesetting, resulting in professional-looking documents.	LaTeX is harder to learn compared to more WYSIWYG editors due to its command-based approach.
LaTeX enforces a structured approach to document creation using its commands and environments.	While it is great for complex formatting, simple formatting might require more effort and time.
It is a perfect tool for writing mathematical equations and symbols.	Unlike WYSIWYG editors, LaTeX requires compiling the document to see the final output.
LaTeX automatically numbers sections, figures, tables, equations, and references which saves users time.	Collaboration can be difficult if collaborators are not familiar with LaTeX or do not have the tools to work with it.
LaTeX provides you with simple cross-referencing within the document, so it is accurate and easy to navigate.	For simple documents with minimal formatting requirements, LaTeX may seem too complex.
It is easy to integrate with BibTeX or BibLaTeX for managing citations and generating bibliographies.	LaTeX errors and issues can sometimes be cryptic, especially for beginners.
LaTeX files are plain text, making them amenable to version control systems like Git, which makes them good for collaborative writing.	LaTeX allows high customization, but to fine-tune the document’s appearance you need to understand LaTeX templates and packages.
LaTeX is widely spread and accepted in academic and scientific communities.	Although LaTeX produces PDFs, some specific formatting might not translate well across different PDF viewers.

It is worth mentioning that most of the cons of LaTeX are already solved with a big variety of cross-platform applications to view, convert, or edit LaTeX which are usually WYSIWYG and easy-to-use.

Common LaTeX file problems

Working with LaTeX can sometimes lead to various challenges and problems. Let’s take a look at some common issues that users might encounter:

Compilation errors

Reasons for LaTeX compilation errors

LaTeX documents must be compiled to produce the final output. Compilation errors can occur for various reasons, from simple syntax mistakes to more complex issues related to package conflicts or document structure .Here are some common reasons for LaTeX compilation errors:

Syntax errors like incorrect use of LaTeX commands, missing backslashes (), or mismatched braces ({}).
Missing or improperly imported or installed packages.
Unclosed environments (like \begin{...} without a corresponding \end{...}).
Using special characters that have special meaning in LaTeX, like the underscore (_).
Non-ASCII characters might also lead to encoding issues and compilation errors.
Incorrect file paths or missing image files.
Specifying incorrect or conflicting placement options (e.g., [h] for “here” and [t] for “top”) for figures and tables.
Issues with BibTeX or BibLaTeX entries, like missing required fields or incorrect entry types.
Package conflicts.
Large documents can exceed memory limits or compilation time limits.
Custom macros or commands with errors in their definitions.
Using the wrong character encoding.
Using commands that are not defined in the document or missing required packages.
Incorrect font declarations or font packages that are not installed.
Documents that rely on external dependencies, like certain fonts or styles, can fail to compile if those dependencies are missing.
Incorrect usage of math mode commands, like missing dollar signs ($).
Using commands or settings that are incompatible with the chosen document class.

How to fix LaTeX file compilation issues?

Check LaTeX code for syntax errors, missing braces, and unmatched environments.
Ensure that required packages are properly imported and that package conflicts are resolved.
Comment out sections of your code and compile incrementally to locate the specific source of the error.
Refer to LaTeX documentation or relevant resources to understand if you correctly use the commands and environments.
If the issues are complex, try compiling a simple LaTeX document to verify that the problem is not due to the LaTeX installation.
Use real-time tools to spot and correct errors.

Missing packages

LaTeX documents often rely on packages to provide additional features and formatting options. If these packages are not properly imported or installed, it may lead to failure.

How to fix the missing LaTeX package issue?

Look at the error message that indicates which package is missing. It usually includes the package name and possibly a description of the command or environment to use.
Check the documentation of the missing package to understand its purpose and how to use it. You can usually find package documentation on CTAN or using search engines.
To import the missing package write in your LaTeX document’s preamble (the area between \documentclass and \begin{document}), and add the \usepackage command. For example:

1\usepackage{missing-package-name}

Use the package manager that comes with your distribution to make sure your TeX distribution (e.g., TeX Live, MiKTeX) is up to date.
If you face conflicts between packages, try finding alternative packages or adjusting your document’s requirements.
Ensure that the package name is written correctly. Note that LaTeX package names are case-sensitive.
Some packages might have dependencies on other packages, so make sure those dependencies are also included.
If the compilation still fails, review the compilation log for more information about the error.

Figures and tables placement

How to adjust figure and table placement in LaTeX?

Working with LaTeX you may face that it sometimes moves figures and tables to optimize page layouts, which might not align with your intentions. To place figures and tables in LaTeX documents can be done using various positioning options and commands. LaTeX provides different placement specifiers that you can use to guide the positioning of your figures and tables.

Placement Specifiers:

[h]: Place the figure/table “here” (approximately at the current location).
[t]: Place the figure/table at the “top” of a page.
[b]: Place the figure/table at the “bottom” of a page.
[p]: Place the figure/table on a dedicated “page” for floats.
[!htbp]: Use a combination of placement options to maximize the chances of placing the float where you want it. For example:

1\begin{figure}[htbp] 
2    % figure content here 
3\end{figure}

To change the number of floats on a page use \setcounter{totalnumber} and \setcounter{topnumber} commands. For example, to allow more floats at the top of a page:

1\setcounter{totalnumber}{4} % Total number of floats on a page 
2\setcounter{topnumber}{3} % Number of floats at the top of a page

To modify the default float placement options globally in your document’s preamble use the \floatplacement command. For example:

1\floatplacement{figure}{htbp} 
2\floatplacement{table}{htbp}

Using the float Package provides additional control over float placement. It introduces the H specifier that places the float exactly where it appears in the code. This can be useful when you want strict control over placement.

1\usepackage{float} 
2% ... 
3\begin{figure}[H] 
4    % figure content here 
5\end{figure}

If you don’t want the object to float and want to place it exactly where it’s defined, use the caption package’s \captionof command.

1\usepackage{caption} 
2% ... 
3\begin{minipage}{\textwidth} 
4    \centering 
5    \includegraphics{example-image} 
6    \captionof{figure}{This is a caption} 
7\end{minipage}

To adjust placement manually recognize content or break up large figures/tables into smaller ones.
Use online editors where you will be able to drag and drop figures and tables to see how they fit on the page.

Spacing and line breaks

LaTeX’s automatic spacing and line-breaking rules might not always produce the desired results. This may cause awkwardly formatted text or large gaps between words.

How to deal with spacing and line breaks in LaTeX?

To edit spacing and line breaks in LaTeX you will need to use a combination of commands and environments to control the formatting of your document. These commands and techniques can be useful for fine-tuning your document’s appearance when necessary:

LaTeX handles spacing between words automatically, but in some cases, you need to adjust the spacing manually.

\ - indicates a space that should not be stretched between words.
~ - creates a non-breaking space and prevents line breaks between the words.
\hspace{length} - inserts horizontal space of a specified length.

To insert vertical space of a specified length use the - \vspace{length} command.
Use the next commands to manually adjust line breaks:

\\ - to create a line break in a paragraph.
\newline - for a line break similar to \\.
\linebreak - makes a line break but tries to avoid excessive stretching of interword spaces.
\newline and \linebreak are similar, but the latter is preferable when you want to avoid large gaps.

Use the next commands to manually adjust the paragraph spacing:

\par - inserts a new paragraph.
Blank lines: Leave a blank line between paragraphs in your source code to create a new paragraph in the output.

Use the next commands to manually control vertical space:

\smallskip, \medskip, \bigskip - Insert small, medium, or large vertical spaces respectively.

Use the setspace package to manually adjust the line spacing:

1\usepackage{setspace} 
2\singlespacing % Single spacing 
3\onehalfspacing % 1.5x spacing 
4\doublespacing % Double spacing

Use the next commands to manually control page breaks:

\pagebreak - inserts a page break.
\newpage - starts a new page.
\clearpage - ends the current page and flushes all pending floats, starting a new page.

Use the next commands to manage horizontal alignment:

center - centers the content.
flushleft- left-aligns the content.
flushright - right-aligns the content.

Cross-referencing issues

How to deal with cross-referencing issues in LaTeX?

Cross-referencing allows you to refer to sections, figures, tables, equations, and other elements within your document. Incorrect or missing references can occur if you don’t update them after making changes to your document’s structure. To deal with it in LaTeX you need to understand how to set up and use labels, references, and citations correctly. Here’s a guide to help you manage cross-referencing in LaTeX:

To set labels you need to assign a label to that element using the \label{label_name} command. For example:

1\section{Introduction} 
2\label{sec:intro}
3   
4\begin{figure} 
5    \includegraphics{example-image} 
6    \caption{A sample figure.} 
7    \label{fig:sample} 
8\end{figure}

To refer to labeled elements use the \ref{label_name} command. For instance:

1In Section \ref{sec:intro}, we discuss... 
2Figure \ref{fig:sample} shows...

To refer to the page number references, use the \pageref{label_name} command:

1The details are provided in Section \ref{sec:intro} on page \pageref{sec:intro}.

To cross-reference equations, use the amsmath package and label equations using \label{eq:label_name}. Reference equations with \eqref{eq:label_name} to include parentheses around the equation number:

1\begin{equation} 
2    E = mc^2 
3    \label{eq:einstein} 
4\end{equation}
5 
6As shown in Equation \eqref{eq:einstein}...

To manage citations and cross-references to bibliography entries, use BibTeX or BibLaTeX. You’ll need to:

Add bibliography entries to a .bib file.
Use the \cite{key} command to cite references.
Include \bibliography{filename} or \addbibresource{filename.bib} to add the bibliography to your document.

Sometimes, when you add or change references, you might need to compile your document multiple times (usually two or more times) to ensure the references are resolved correctly. This is because LaTeX uses auxiliary files to store information about labels and references.
Use the cleveref package that provides enhanced cross-referencing capabilities, automatically determining the type of the reference and adding context (e.g., “Section” or “Figure”) as needed. The hyperref package enhances cross-referencing and also makes references to clickable links in the generated PDF.

1\usepackage{cleveref} % Better cross-referencing 
2\usepackage{hyperref} % Hyperlinked references

Font and formatting consistency

How to maintain font and formatting consistency in LaTeX?

Achieving consistent font sizes, styles, and formatting across different sections of the document may sometimes be a challenging task. It can be done with various LaTeX commands, packages, and settings to achieve this.

Choose a document class that aligns with your desired formatting style, such as article, report, book, or specific journal templates. Additionally, use the next packages to customize the formatting:

\usepackage[margin=1in]{geometry} - adjusts margins.
\usepackage{fontspec} - for custom fonts (XeLaTeX or LuaLaTeX).
\usepackage{setspace} - adjusts line spacing.
\usepackage{titlesec} - customizes section titles.
\usepackage{enumitem} - customizes lists.

Use the fontspec package with XeLaTeX or LuaLaTeX to select custom fonts

1\usepackage{fontspec} 
2\setmainfont{Times New Roman} % Replace with your desired font

If using PDFLaTeX, you can use packages like mathptmx (Times), helvet (Helvetica), or palatino (Palatino) for font selection.

To adjust line spacing use the setspace package:

1\usepackage{setspace} 
2\onehalfspacing % or \doublespacing

To customize lists use the enumitem or titlesec package:

1\usepackage{titlesec} 
2\titleformat{\section}{\normalfont\Large\bfseries}{\thesection}{1em}{} 
3\titleformat{\subsection}{\normalfont\large\bfseries}{\thesubsection}{1em}{}

To customize captions for tables and figures:

1\usepackage{caption} 
2\captionsetup[table]{font=small, labelfont=bf} 
3\captionsetup[figure]{font=small, labelfont=bf}

Use the parskip package to control paragraph spacing without indentation. Use setlength to adjust paragraph indentation:

1\setlength{\parindent}{0pt} % No indentation

To customize headers and footers use the fancyhdr package:

1\usepackage{fancyhdr} 
2\pagestyle{fancy} 
3\fancyhead{} % Clear header 
4\fancyfoot{} % Clear footer 
5\fancyhead[R]{\thepage} % Page number on the right

To control page numbering style and position use the fancyhdr package or the pagestyle commands.

Math equation alignment

It is not always an easy task to align formulas correctly, especially when there are a lot of them or complex alignments. In LaTeX, you can align equations using various environments and commands provided by the amsmath package. All the needed information about typesetting LaTeX formulas is described in the articles of the Typesetting math formulas with standard LaTeX chapter.

Setting margin and page layout

To manage margins and page layout use the geometry package that allows you to control various aspects, such as margins, page size, headers, and footers.

To adjust the margins of your document specify the desired margin dimensions using options like left, right, top, and bottom. Here’s an example:

1\usepackage[left=1.5in, right=1.5in, top=1in, bottom=1in]{geometry}

To change the paper size, use the paper option along with predefined paper sizes like a4paper, letterpaper, etc. For example:

1\usepackage[a4paper, margin=1in]{geometry}

To customize headers and footers use options like headheight, headsep, footskip to control these dimensions.
To create a document with multiple columns, use the multicol package:

1\usepackage{multicol} 
2\begin{document} 
3\begin{multicols}{2} 
4    % Content for column 1 
5    \columnbreak 
6    % Content for column 2 
7\end{multicols} 
8\end{document}

Use the setspace package to adjust line spacing:

1\usepackage{setspace} 
2\onehalfspacing % 1.5x spacing

If you want different layouts for odd and even pages, try to use the twoside option with the geometry package. This is common for documents with double-sided printing.

1\usepackage[twoside, inner=1in, outer=1.5in]{geometry}

Remember that when you manipulate the page layout you should take into account printing requirements and readability. Overly narrow margins or unusual layouts might make your document less reader-friendly.

Nested environments

How to deal with problems caused by nested environments in LaTeX?

It can sometimes be challenging to manage nested environments (like lists within lists), especially their formatting and indentation. Here are some tips to deal with problems caused by nested environments:

Check for compatibility because not all environments are compatible when nested. For example, avoid nesting list environments (itemize, enumerate, description) inside each other without proper control over indentation and formatting.
When dealing with nested environments, use braces {} or groups to limit the scope of certain commands. This helps prevent unintended effects on the outer environment.
If you need to include a short mathematical formula within the text, use inline math mode ($...$) instead of entering a full equation environment. to reduce the complexity.
Try not to use commands in the inner environment that are already applied by the outer environment which may lead to formatting inconsistencies.
If the nested environment uses special characters, consider using the \text or \mbox command to escape the special characters and ensure correct rendering.
Use \centering instead of center environment. \centering is a command that doesn’t create an environment and thus avoids some of the spacing problems.
For complex nesting scenarios, consider using packages like environ or xparse that can help manage complex nesting situations more effectively.
Sometimes, a nested environment is not necessary. If possible, simplify your document structure by reducing the depth of nesting.

Non-ASCII characters

Using such characters (e.g., accented letters) in your document might create issues or unexpected character display.

How to deal with non-ASCII characters?

In LaTeX, handling non-ASCII characters requires attention to encoding, font selection, and input methods. Here’s how to work with non-ASCII characters in LaTeX:

LaTeX documents typically use the UTF-8 encoding to support a wide range of characters. To ensure that non-ASCII characters are handled correctly, specify the UTF-8 encoding in the document preamble:

1\usepackage[utf8]{inputenc}

Some fonts included in LaTeX support a broad range of characters, including non-ASCII characters. If you’re working with languages other than English, try to pick fonts that are designed to handle those characters. For example, for Latin scripts with accents, you can use the fontenc package and the T1 font encoding:

1\usepackage[T1]{fontenc}

For more complex scripts like Cyrillic, Greek, or Devanagari, consider using XeLaTeX or LuaLaTeX along with appropriate system fonts.

In LaTeX, you can input accented characters using escape sequences:

1\'e % é 
2\"o % ö 
3\^a % â

Alternatively, you can use the inputenc package to directly input accented characters:

1\usepackage[utf8]{inputenc} 
2%... 
3café % café

Some characters have special meanings in LaTeX (e.g., $, %, _, &). To include them as regular text, use backslashes to escape them:

1\$ % $ 
2\% % % 
3\_ % _ 
4\& % &

For documents in languages other than English, use language-specific packages (e.g., babel or polyglossia) to set the correct language rules for hyphenation and formatting.
For scripts like Arabic, Chinese, or Devanagari, use packages designed to handle those scripts. For instance, you can use the arabtex package for Arabic.

Handling large-size files

How to make a LaTeX file smaller?

LaTeX can sometimes struggle with handling large documents. It is usually noted by longer compilation times or memory issues. Here are several tips to make your LaTeX file smaller :

Remove unnecessary packages because they can contribute to unnecessary overhead.
Use minimal document classes if it suits your needs. Some classes, like article, have less overhead in comparison to more complex classes like book or report.
Avoid excessive use of \input or \include commands for external files.
Optimize images using efficient formats like PNG, WEBP, or JPEG. Use the graphicx package’s draft option to display bounding boxes instead of images during editing.
Whenever possible, use vector-based graphics (PDF, EPS) instead of raster images as they are smaller and can be resized without quality loss.
If you use PDF images, compress them using tools like ghostscript or online services.
If you’re using custom fonts, ensure you’re only including the necessary font files and formats.
Remove any commented-out code or unnecessary comments.
Use abbreviations and macros.
Limit cross-references.
Minimize extra whitespace, line breaks, and indentation.
Limit table of contents depth using the tocdepth command to control the number of section levels included.
Use compression.

Remember that reducing file size is beneficial, but maintaining readability and document structure is equally important.

Incompatible LaTeX packages

Some packages might conflict with each other, causing unexpected behavior or errors.

How to spot incompatible LaTeX packages?

This task can sometimes be challenging, especially when you have a complex document with multiple packages interacting. Here are some strategies to identify and resolve incompatible LaTeX packages:

Compile your document and carefully review the error messages and warnings in the log file to find hints about which packages are conflicting.
Comment out packages one by one to identify which one might be causing the conflict. After each step, recompile and see if the issue persists.
Create a minimal working example(MWE) that replicates the problem you’re facing. By gradually adding packages and content from your original document, you can isolate the source of the issue more effectively.
Check the documentation of the packages you’re using. Some packages might have known incompatibilities with others, and the documentation might provide insights on how to resolve them.
Search online forums.
Use compatibility packages like `fixltx2e which are designed to address incompatibilities between LaTeX packages or older packages and newer versions of LaTeX.
Make sure you’re not using outdated packages that might not be compatible with newer LaTeX versions. Check if there are newer alternatives available.
Review the package documentation to see if there are options to adjust or disable certain features that might be causing conflicts.
Use TeX Live Utility or MiKTeX Console that provides information about installed packages, updates, and compatibility issues.
Upgrading packages to their latest versions can resolve compatibility issues.

Unsupported file types

Supported file types:

.tex - The main LaTeX input file.
.sty - LaTeX style files.
.cls - LaTeX class files.
.bib - BibTeX bibliography files.
.bst - BibTeX style files.
.eps, .pdf, .png, .jpg - Supported image formats that can be included in LaTeX documents using the graphicx package.

Unsupported or incompatible file types:

.doc, .docx - Microsoft Word documents.
.ppt, .pptx - Microsoft PowerPoint presentations.
.xls, .xlsx - Microsoft Excel spreadsheets.
.txt - plain text files are generally supported, but if they contain non-LaTeX-specific formatting, you might need to adjust the content for LaTeX compatibility.
.html, .xml - HTML and XML files .
.svg - Scalable Vector Graphics files.

To deal with unsupported or incompatible file types use conversion tools to get the file of one of the better supported formats.

Conclusion

To draw a conclusion let’s summarize the main rules that let you work with LaTeX files easily:

Learn LaTeX’s syntax and common commands to reduce syntax errors and improve troubleshooting.
Address LaTeX documentation, tutorials, and forums to find solutions to specific problems.
Compile the document step by step (commenting out sections) to locate the source of errors.
Use version control systems like Git to track changes and revert to working versions if needed.
Use online tools that provide real-time collaboration, templates, and built-in error highlighting.
Regularly save incremental versions of your document to avoid losing work due to unexpected issues.
Don’t hesitate to ask for help on LaTeX forums or communities.

What is LaTeX? LaTeX input/output