IPFS Pin Stuck on Pinning? What Each Pin Status Means

You upload a folder to a pinning service, the dashboard says Pinning, and ten minutes later it still says Pinning. Whether that is a problem depends on what the status measures. An IPFS pin stuck on Pinning can mean the service has not yet confirmed that every block under your root CID is stored, which is separate from whether your upload arrived. Below: the statuses AIOZ Pin documents, how to read a pin's real state through the API, and what the docs say about large directories that stay on Pinning for a long time.

TL;DR:

• AIOZ Pin documents three statuses: Pinning (in the queue, awaiting processing), Pinned (stored and pinned on IPFS), and Failed (the upload failed or the graph of data is incomplete)
• The IPFS Pinning Service API standard defines four values, queued, pinning, pinned, and failed, plus an optional status_details field for extra information
• AIOZ Pin's docs warn that a very large directory, such as a 10K-file NFT drop, may show Pinning indefinitely because the upload is too big to validate as a complete graph right away
• You can check a pin in the dashboard file list, with the Node.js SDK's getPinByID, or with GET /pinning/{pinId}, and the API returns both a status and a pinned boolean
• The docs give no time limit or retry policy, so a long Pinning status is a reason to verify availability, not proof of failure

What Pinning, Pinned, and Failed Mean

AIOZ Pin's documentation on getting upload status defines three states. Pinning means your upload is in the queue and waiting for the pinning service to process it. Pinned confirms the data was stored and pinned on the IPFS network. Failed means the upload failed or the graph of data is incomplete.

Those labels are simpler than the open standard that many providers implement. The IPFS Pinning Service API specification lists four values: queued (waiting in the queue), pinning (in progress), pinned (done), and failed. A service can also return extra context in info.status_details. IPFS Pinning Service API: What It Is, Why It Matters covers the standard in full. AIOZ Pin's page lists three labels rather than four, so don't assume the spec's queued and pinning states map one to one onto what you see in the dashboard.

Why a Pin Is a Question About the Whole Graph

The phrase "graph of data is incomplete" in the Failed definition points to the cause. IPFS content is a graph of blocks, and a pin covers more than the root. The IPFS docs describe a recursive pin as one that pins a given block and all of its children, while an indirect pin is what a child block becomes when its parent is pinned recursively. IPFS Garbage Collection: What Unpinning Actually Does explains how those pin types decide what gets kept.

For a single image that graph might be a handful of blocks. For a directory holding 10,000 NFT files, it is a root block that links to 10,000 file DAGs, each with its own blocks. The pin cannot be Pinned until every block reachable from that root is present. That is why the docs include this warning: if you have a large upload with numerous blocks, such as a directory for a 10K NFT drop, the service may show Pinning indefinitely, because the upload is too large for immediate validation of its completeness as a graph.

The docs do not say how AIOZ Pin performs that validation, so I won't guess. In practice, a large directory can legitimately sit on Pinning long after the upload finished.

How to Check a Pin's Real State

There are three documented ways to read a pin's status.

• In the dashboard, the file listing page shows each upload with its current status.
• In the Node.js SDK, the getPinByID(pinId) method returns the pin, including its status (getting started with the SDK).
• Over HTTP, send a GET request to /pinning/{pinId} and read the response.

The API route is the most useful when you are debugging, because it returns structured fields instead of a label. A minimal call, using the headers AIOZ Pin's API reference specifies for pinning endpoints, looks like this:

const BASE = 'https://api.aiozpin.network/api'
const headers = {
  pinning_api_key: process.env.AIOZ_PIN_API_KEY!,
  pinning_secret_key: process.env.AIOZ_PIN_SECRET_KEY!,
}

async function getPinDetails(pinId: string) {
  const res = await fetch(`${BASE}/pinning/${pinId}`, { headers })
  return res.json()
}

const { data } = await getPinDetails('YOUR_PIN_ID')
console.log(data.status, data.pinned, data.size)

The documented response includes status, a pinned boolean, size in bytes, is_dir, is_pin_by_hash, and a sub_hash_status string. Reading those together tells you more than the dashboard label alone. A directory (is_dir) with a large size that has not flipped to pinned is the documented slow case. A pin created from an existing CID is flagged is_pin_by_hash; with no upload involved, the content has to come from somewhere on the network, so findability matters there. The reference does not explain sub_hash_status, so treat it as something to log and watch rather than interpret.

The list endpoint also accepts a pinned filter with the values all, true, and false. Be careful with false: the API reference shows pinned: false after you unpin something, so that filter will also return pins you removed on purpose.

What to Do When a Pin Will Not Move

Work through these in order.

1. Read the status through the API as well as the dashboard. That gives you an unambiguous record of what the service reports, with the pinned boolean next to it.
2. Check is_dir and size. A large directory is the one case the docs call out for staying on Pinning.
3. Spot-check availability. Fetch a handful of files through your gateway to confirm the content is reachable. Sample, don't crawl: the AIOZ Pin public gateway is meant for testing, and its documented limits are 15 requests per minute per CID across all IP addresses and 200 per minute per IP. Premium gateways have no predefined limit.
4. If the status is Failed, re-upload from your original files. The docs describe an incomplete graph as a failure, so until you see Pinned, your source files are the only complete copy. Keep them.
5. If Pinning persists far longer than you expect, contact the AIOZ team. The docs list their support channels; include the pin ID and the CID when you write.

What the Docs Do Not Say

Several things you might want to know are not documented. There is no stated timeout for how long a pin can stay on Pinning, and no retry policy after a Failed result. The API reference types status as a plain string without listing its possible values, so the Pinning, Pinned, and Failed labels come from the upload-status tutorial rather than the API reference. The details response has no status_details field like the one in the open spec, so you cannot count on a reason string, and the sub_hash_status field it does carry is not explained. There is also no recommended maximum directory size. For what AIOZ Pin does document about keeping a Pinned file available, see How AIOZ Pin Keeps Files Online. Until AIOZ Pin documents the rest, treat any specific number you read elsewhere, including in a forum thread about a different service, as a guess about someone else's system.

Frequently Asked Questions

Why is my IPFS pin stuck on Pinning? Pinning means the service has not yet confirmed the whole graph of data under your root CID. AIOZ Pin's docs say a very large directory, such as a 10K-file NFT drop, may show Pinning indefinitely because it is too large to validate as a complete graph right away.

How long should pinning take on AIOZ Pin? The docs do not give a time. The only slow case they describe is a large directory with many blocks.

What does Failed mean? The upload failed or the graph of data is incomplete. Re-upload from your original files, and keep them until the status reads Pinned.

How do I check a pin's status programmatically? Call GET /pinning/{pinId} and read status and pinned, or use getPinByID(pinId) in the Node.js SDK.

If some files in my directory load through a gateway, is it pinned? Not necessarily. Whether a gateway can serve a file and whether the service has confirmed the whole graph are separate questions, and Pinned is the status AIOZ Pin documents as confirmation.

Can I make a large directory pin faster? The docs describe no way to speed it up. Since the stated cause is the size of the graph, smaller directories give the service less to validate, but that is an inference, not documented behavior.

Related Reading

• How AIOZ Pin Keeps Files Online: Replication and Proofs - what happens to a pin after it reaches Pinned
• IPFS Pinning Service API: What It Is, Why It Matters - the open standard behind the four status values
• IPFS Garbage Collection: What Unpinning Actually Does - recursive and indirect pins in more detail
• Getting Started with the AIOZ Pin Node.js SDK: A Guide - where getPinByID fits in an SDK workflow
• AIOZ Pin CLI Tutorial: Login, Pin, List, and Unpin Files - checking pins from the command line

References

• AIOZ Pin docs: Getting upload status
• AIOZ Pin docs: Pinning API
• AIOZ Pin docs: Limits
• IPFS Pinning Service API specification
• IPFS Docs: Pin files