---
title: "Placeholders not detected or places misaligned"
description: "Fix placeholders that SignatureAPI doesn't find and places that land in the wrong spot, with the error each problem returns and how to check a file first."
canonical: "https://signatureapi.com/docs/troubleshooting/places"
source: "https://signatureapi.com/docs/troubleshooting/places.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T13:06:40Z"
---

# Placeholders not detected or places misaligned

Fix placeholders that SignatureAPI doesn't find and places that land in the wrong spot, with the error each problem returns and how to check a file first.

_Last verified against API version 1.18.0._

Places go wrong in two ways: SignatureAPI can't match a place to its position, and the create request fails, or the request succeeds and a place shows up somewhere you didn't expect. This page covers both.

## Check the file first

Before you create an envelope, [upload the file](https://signatureapi.com/docs/api/resources/uploads/create) and call [Retrieve upload structure](https://signatureapi.com/docs/api/resources/uploads/structure). It lists every placeholder SignatureAPI finds, with its page and position, and an `errors` array for keys that are invalid or repeated. If a placeholder isn't in that list, SignatureAPI can't see it.

The same call returns the size of every page, in points, which you need for [fixed positions](https://signatureapi.com/docs/api/resources/places/positioning#fixed-positions).

## The request fails

Each of these is a `422` response to the create request, so no envelope is created. The `detail` names the place or placeholder.

| Error                                                                                                        | Cause                                                                                          | Fix                                                           |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`invalid-places`](https://signatureapi.com/docs/v1/errors/invalid-places)                                   | A place has no matching `[[key]]` in the document and no fixed position.                       | Add the placeholder text, or give the place a fixed position. |
| [`invalid-placeholder`](https://signatureapi.com/docs/v1/errors/invalid-placeholder)                         | The document has a `[[key]]` that no place uses.                                               | Add a place with that key, or remove the text.                |
| [`duplicate-placeholder`](https://signatureapi.com/docs/v1/errors/duplicate-placeholder)                     | The same placeholder appears twice.                                                            | Give each place its own key and placeholder.                  |
| [`placeholder-position-conflict`](https://signatureapi.com/docs/v1/errors/placeholder-position-conflict)     | A place has a fixed position and a matching placeholder.                                       | Keep one of the two.                                          |
| [`mixed-placeholders`](https://signatureapi.com/docs/v1/errors/mixed-placeholders)                           | The document mixes legacy signature placeholders, such as `[[client.signature]]`, with places. | Use places and `[[place_key]]` placeholders only.             |
| [`place-outside-page`](https://signatureapi.com/docs/v1/errors/place-outside-page)                           | A place sits partly or fully outside its page.                                                 | Move it inside the page.                                      |
| [`fixed-position-outside-document`](https://signatureapi.com/docs/v1/errors/fixed-position-outside-document) | A fixed position names a page the document doesn't have.                                       | Use a page number from 1 to the document's page count.        |
| [`no-signing-place`](https://signatureapi.com/docs/v1/errors/no-signing-place)                               | A signer has no signature or initials place.                                                   | Add one with that signer's `recipient_key`.                   |

## SignatureAPI doesn't find a placeholder

When a placeholder is in the file but missing from the upload structure, check these:

- **The text must be real text.** SignatureAPI reads the document's text. A placeholder inside an image or a scanned page isn't text. Try to select and copy it in a PDF reader: if you can't, neither can SignatureAPI. Add it as text in the source file and export again.
- **The key must be valid.** A key has 1 to 32 characters: lowercase letters, digits and underscores, starting with a letter. `[[Client_Sign]]` and `[[client-sign]]` are not valid keys; `[[client_signs_here]]` is.
- **Use double square brackets.** `[[client_signs_here]]` positions a place. `{{client_signs_here}}` is a [template field](https://signatureapi.com/docs/api/resources/documents/templates) in a DOCX and is replaced with data, not with a place.
- **The key must match exactly.** The text between the brackets must equal the place's `key`, character for character.

## A place lands in the wrong spot

### Fixed positions measure to the bottom-left corner

`top` is the distance from the top edge of the page to the **bottom-left** corner of the place, not its top-left corner. A place positioned as if `top` pointed at its top edge sits one place-height too high. Add the place's height to `top` to correct it.

### Positions are in points

`top` and `left` are in points: 1 point is 1/72 inch, about 0.35 mm. Values in pixels or millimeters put the place in the wrong spot or off the page. A US Letter page is 612 × 792 points, and an A4 page is 595 × 842. See [Points and page sizes](https://signatureapi.com/docs/api/resources/places/positioning#points-and-page-sizes).

### Pages start at 1

`page` counts from 1, so `"page": 2` is the second page. `"page": 0` fails validation, and a page past the end of the document fails with `fixed-position-outside-document`.

### The place is bigger or smaller than the placeholder

A placeholder sets where a place goes, not how big it is. A signature place is always 2.5 times as wide as its `height`, which is 20 to 60 points (60 by default), whatever the size of the placeholder text. If the signature covers nearby text, lower `height` or leave more room around the placeholder. See [Signature](https://signatureapi.com/docs/api/resources/places/signature).

### The placeholder shows on the signed document

The rendered place covers the placeholder, but a colored placeholder can show around it. Set the placeholder text color to white in the source file so only the place remains. See [Hide the placeholder](https://signatureapi.com/docs/api/guides/how-to/use-placeholders#hide-the-placeholder).

## Try positions before you send

On the [Positioning](https://signatureapi.com/docs/api/resources/places/positioning#fixed-positions) page, drag a place over a Letter or A4 page, or a page sized from your own PDF, to read its `top` and `left` values. Then send a [test envelope](https://signatureapi.com/docs/api/test-mode) and open its ceremony to see the result on the real document. Test envelopes are free.

## Related

- [Positioning](https://signatureapi.com/docs/api/resources/places/positioning): placeholders and fixed positions.
- [Use placeholders](https://signatureapi.com/docs/api/guides/how-to/use-placeholders): a worked example.
- [Troubleshooting templates](https://signatureapi.com/docs/troubleshooting/templates): when the DOCX merge itself fails.
