Tokr for Craft CMS

Troubleshooting

Thumbnails are blank

Almost always the refresh has stopped running.

TikTok's cover_image_url values are signed and expire about six hours after they are issued. Tokr's job is to replace them before that happens. If images that worked this morning are broken this afternoon, the images did not break — the refresh did.

Check, in order:

  1. Tokr → Accounts — what does Last refreshed say? If it is hours old, nothing is refreshing.
  2. Is your queue running? If Refresh in the background is on, refreshes are queue jobs and a stalled queue stops them.
  3. Is the cron entry running, if you use one? php craft tokr/refresh --force by hand will tell you immediately.
  4. Is refreshInterval set above six hours in config/tokr.php? The CP field caps at 18000, the config file does not stop you going higher.

"This account's TikTok authorization has expired"

The refresh token is dead. They last a year, and they also die if the account holder revokes access from TikTok's side, or if the app's credentials change.

There is no way to renew this without a person: open the account and press Reconnect, which runs the authorization flow again. The stored videos stay put in the meantime, so the feed keeps rendering — it just stops updating.

redirect_uri error from TikTok

TikTok compares the redirect URI as a literal string. Common mismatches:

  • http:// where the app has https://
  • a trailing slash on one side and not the other
  • www. on one side and not the other
  • a staging domain that was never added to the app

The exact value Tokr sends is shown at Settings → Plugins → Tokr. Copy it from there into the TikTok app rather than typing it.

Behind a proxy or load balancer, Craft may build the URL from the internal host. Set redirectUri in config/tokr.php to the public value.

"TikTok API error (access_token_invalid)"

The access token was rejected. Tokr refreshes access tokens automatically, so seeing this usually means the refresh itself failed — check the account for a Needs reconnecting status, and check that the client key and secret in your settings still match the TikTok app.

If you rotated your Craft securityKey, the stored tokens can no longer be decrypted and every account has to be reconnected. Tokr logs a warning rather than crashing when this happens.

No videos, but the account connected fine

  • The account has no public videos. The Display API only returns public ones.
  • video.list was not granted. Check the scopes on the TikTok app.
  • The app is in sandbox and the account is not a target user. Connection can succeed while the video list comes back empty.

Press Refresh now on the account — the resulting error, if any, is shown on the account screen.

The feed renders but looks unstyled

Include Tokr's CSS may be off in the settings. If it is on and styles still are not appearing, check whether the feed is being rendered inside a {% cache %} block — Craft skips asset bundle registration on a cache hit, so the CSS never gets added. Render the feed outside the cache, or register the bundle yourself.

Only 20 videos come back

That is TikTok's page size for video/list. Tokr pages through it to reach Videos Per Refresh, so if you are seeing exactly 20, the paging stopped early — usually because the account has no more public videos.

A video I deleted is still showing

Turn Keep removed videos off (it is off by default) and refresh. With it on, Tokr keeps rows TikTok no longer returns, and those thumbnails will break permanently once their URLs expire.

Changes to a doc or template are not showing

Clear the compiled template cache:

php craft clear-caches/compiled-templates