Troubleshooting image creation

Modified: 26 Jan 2023 22:12 UTC

This topic provides details on troubleshooting errors while creating custom images. See Creating your own images for full details on image creation.

Immediate and Asynchronous Errors

Image creation ultimately calls the Joyent Cloud API CreateImageFromMachine endpoint. This call can fail immediately due to validation errors, for instance. Or the image creation could fail asynchronously, at a later stage in the process, if, for example, there was an error in preparing the snapshotted instance.

An example of an immediate error is what happens if you try to give an image a name that contains illegal characters. In this example, we've tried to name the instance foo~bar, but that name contains an illegal ~ character.

This is what the error looks like if you are using triton:

$ triton image create <container> foo~bar 1.0.0
triton image create: error: error creating image
    name: Invalid: image name has invalid characters (only alpha-numeric characters and " ", ".", "-", "_" and "/" are allowed): invalid image data: name

Alternatively, if using sdc-createimagefrommachine

$ sdc-createimagefrommachine --machine eeeda403-59ee-4a1b-a674-bbd7d1ca55d9 --name "foo~bar" --imageVersion=1.2.3
invalid image data: name

If you are using the HTTP API, the response would look like this:

    HTTP/1.1 422 Unprocessable Entity
    content-type: application/json
    content-length: 413
    access-control-allow-origin: *
    access-control-allow-headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
    access-control-allow-methods: GET, HEAD, POST
    access-control-expose-headers: Api-Version, Request-Id, Response-Time
    connection: Keep-Alive
    content-md5: Q9a1XQBHShbKgT7ADF6Tgw==
    date: Wed, 11 Dec 2013 19:02:40 GMT
    server: Joyent SmartDataCenter 7.1.0
    api-version: 7.1.0
    request-id: ceb8a270-6296-11e3-9c6e-ad55ae466bcb
    response-time: 277
    x-request-id: ceb8a270-6296-11e3-9c6e-ad55ae466bcb
    x-api-version: 7.1.0
    x-response-time: 277

    {
        'code': 'ValidationFailed',
        'message': 'invalid image data: name',
        'errors': [
          {
            'field': 'name',
            'code': 'Invalid',
            'message': 'image name has invalid characters (only alpha-numeric characters and " ", ".", "-", "_" and "/" are allowed)'
          }
        ]
    }

If the image creation process fails asynchronously. sdc-getimage will report that the image is in the failed state. The error field provides additional information about the failure. For example:

    {
        "id": "d4ac3751-64f1-6929-ee92-fe01e14743b7",
        "name": "Briseis",
        "version": "1.2.3",
        "requirements": {},
        "owner": "5005c17b-d2de-9949-afe4-fb372fd7357f",
        "public": false,
        "state": "failed",
        "error": {
            "code": "PrepareImageDidNotRun",
            "message": "prepare-image script did not run on VM 670e2535-9f3a-494f-d066-a280f4ab0d85 boot"
        }
    }

In both immediate and asynchronous errors, the result includes an error code. The following sections describe the kinds of errors you may encounter.

See the CreateImageFromMachine and GetImage for a full listing of error codes.

NotAvailable

Not all images can be used as the basis for a prototype instance. If you try to create an image from an instance that uses an unsupported SmartOS or Linux image, you will see this error.

PrepareImageDidNotRun

As part of the image creation process, a prepare-image script runs on your prototype instance to remove instance-specific data, such as logs and host SSH keys. You'll see this error if the prepare-image did not run.

The most common cause for this error is that your prototype instance is if it's missing the required guest tools located in /lib/smartdc. This can happen, for example, if the guest tool files were accidentally deleted when you were preparing your prototype instance.

VmHasNoOrigin

Some pre-existing and migrated images are not supported for image creation. This error indicates that the instance's underlying ZFS dataset is not associated with a Joyent Machine Image, required for image creation.

NotSupported

This error usually means that you are trying to create a custom image from a prototype instance that was provisioned from a custom image.

A custom image cannot be used as the basis for another custom image.

Modifications to a prototype Linux instance that can lead to failures

There are a few changes to a prototype instance that can cause the image creation process to fail