Why did my hidden layer not render

It depends on the layer type, and the two rules are opposites. A hidden text layer is kept as a fillable slot. A hidden smart object is not exposed at all. A layer the file shows can also be left out of a single render, which Hide a layer for one render covers.

Why this happens

A text layer switched off in Photoshop is usually a parked alternative: a second language, a price, a name. It survives the upload as a slot and waits for you to fill it per render. A hidden smart object is not offered as a slot at all, so smart_objects leaves it out and it does not render. This is confusing because:

Both look the same in the Layers panel.
The upload succeeds either way.
An unfilled text slot is as absent from a render as a missing smart object.

How to identify this issue

The upload response and Retrieve a single PSD mockup both list every smart object and text layer in the template, each with its uuid.

Read an existing template back rather than uploading again. A second upload registers a second template with its own uuids, as Upload a PSD explains.

A smart object is missing from smart_objects, and the upload carries the advisory code PSD_HIDDEN_SMART_OBJECTS. A smart object hidden inside another one follows the same rule: it is missing from the smart_objects of its parent smart object’s entry, and it counts toward the same code.
A text layer is in text_layers with a usable uuid, and missing only from renders you left it out of.
A uuid outside that list returns TEXT_LAYER_NOT_FOUND, which Text layers lists, rather than a render.
The file has neither a visible smart object nor a text layer, so the upload itself fails with NO_SMART_OBJECTS, which Errors lists. A hidden text layer counts here, so a file that has one does not hit this.
GET /api/v1/psd-mockups/{uuid}/layers lists every layer of the template, and a layer switched off in the file shows visible as false there.

Solution

A hidden smart object. Make the layer visible in Photoshop and upload again. The new upload returns a fresh template with a new mockup_uuid. A hidden text layer. Nothing to fix. Send an entry under text_layers and it renders; leave it out and that line stays hidden. Your source file is unchanged either way. See Render a PSD mockup and Text layers.

One template therefore carries optional lines, personalised fields and language variants. Design the alternatives once, hide them, and switch each on per render.

A layer that is listed but renders unchanged. A different problem. TEXT_OVERRIDE_NOT_APPLIED or TEXT_LAYER_NOT_EDITABLE in warnings means the layer kept its original appearance, and Text layers says which limit you hit. PSD compatibility covers what renders as authored.

Hide a layer for one render

A layer the file shows can be left out of one render without changing the template. Read the template’s layers, then name the ones to leave out in hidden_layers on Render a PSD mockup. GET /api/v1/psd-mockups/{uuid}/layers returns every layer nested the way Photoshop’s Layers panel shows it, front-most first, each with its uuid, name, kind, visible and children. An artboard has kind set to artboard, and its own layers are listed right before it at the top level rather than as its children. A smart object whose contents hold layers you can fill lists those layers as its children, so a layer inside a smart object can be left out too. A smart object, text layer or group carries the same uuid it has in smart_objects, text_layers and group_layers, and reading the list costs no credits.

Layers response, shortened

{
  "success": true,
  "data": {
    "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "layers": [
      {
        "uuid": "423e4567-e89b-12d3-a456-426614174003",
        "name": "Sleeve badge",
        "kind": "group",
        "visible": true,
        "children": [
          {
            "uuid": "523e4567-e89b-12d3-a456-426614174004",
            "name": "Badge text",
            "kind": "text",
            "visible": true,
            "children": []
          }
        ]
      },
      {
        "uuid": "923e4567-e89b-12d3-a456-426614174008",
        "name": "Nickname",
        "kind": "text",
        "visible": false,
        "children": []
      }
    ]
  }
}

The badge is a group, so its one uuid leaves the group and everything inside it out of the render:

const response = await fetch("https://api.sudomock.com/api/v1/renders", {
  method: "POST",
  headers: {
    "x-api-key": "sm_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "hidden_layers": [
      "423e4567-e89b-12d3-a456-426614174003"
    ]
  }),
});

const data = await response.json();
console.log(data);

<?php

$payload = <<<'JSON'
{
  "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "hidden_layers": [
    "423e4567-e89b-12d3-a456-426614174003"
  ]
}
JSON;

$ch = curl_init("https://api.sudomock.com/api/v1/renders");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: sm_your_api_key",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

payload = {
    "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "hidden_layers": [
        "423e4567-e89b-12d3-a456-426614174003"
    ]
}

response = requests.post(
    "https://api.sudomock.com/api/v1/renders",
    headers={"x-api-key": "sm_your_api_key"},
    json=payload,
)

response.raise_for_status()
print(response.json())

require "net/http"
require "uri"

uri = URI("https://api.sudomock.com/api/v1/renders")
request = Net::HTTP::Post.new(uri)
request["x-api-key"] = "sm_your_api_key"
request["Content-Type"] = "application/json"

request.body = <<~JSON
  {
    "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "hidden_layers": [
      "423e4567-e89b-12d3-a456-426614174003"
    ]
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "hidden_layers": [
    "423e4567-e89b-12d3-a456-426614174003"
  ]
}`)

	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/renders", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", "sm_your_api_key")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String payload = """
{
  "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "hidden_layers": [
    "423e4567-e89b-12d3-a456-426614174003"
  ]
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/renders"))
    .header("x-api-key", "sm_your_api_key")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

var payload = """
{
  "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "hidden_layers": [
    "423e4567-e89b-12d3-a456-426614174003"
  ]
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sudomock.com/api/v1/renders");
request.Headers.Add("x-api-key", "sm_your_api_key");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var client = new HttpClient();
var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

curl -X POST "https://api.sudomock.com/api/v1/renders" \
  -H "x-api-key: sm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mockup_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "hidden_layers": [
      "423e4567-e89b-12d3-a456-426614174003"
    ]
  }'

Hiding a group hides every layer inside it, and a layer clipped to a hidden layer is hidden with it, as in Photoshop.
A layer hidden inside a smart object’s contents is hidden in every copy of that smart object.
One render takes up to 50 entries, and a uuid listed twice counts once.
hidden_layers works on its own or beside smart_objects, text_layers and group_layers, and the render is billed like any other.
A layer cannot be hidden and edited in the same request. Such a request returns 422.
A smart object that receives an asset cannot have layers inside it hidden in the same request. Such a request returns 422 with NESTED_SLOT_CONFLICT.
A uuid this template does not have fails the render with LAYER_NOT_FOUND, a 400.
Hiding only takes layers away. A layer switched off in the file stays off, apart from a text layer you fill.

If the layer still does not render

Confirm the layer is switched on in the file you actually uploaded.
Check that the render does not name the layer, a group or smart object around it or the layer it is clipped to in hidden_layers.
Read the template back and compare the uuid you send against the list.
Check warnings on the upload and on the render.
Contact support with the template uuid and the response.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Choosing an approach

Troubleshooting

Working with the API

Account and billing

Changes

Why did my hidden layer not render

Why this happens

How to identify this issue

Solution

Hide a layer for one render

If the layer still does not render

​Why this happens

​How to identify this issue

​Solution

​Hide a layer for one render

​If the layer still does not render

Why this happens

How to identify this issue

Solution

Hide a layer for one render

If the layer still does not render